--- name: harness-knowledge-query description: "在规划、实现或排查前，通过 hunter-harness CLI 查询远端项目知识库。远端不可用时直接报告不可用，不建立本地索引或离线回退。" --- # harness-knowledge-query 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果： - 不创建或读取 `.harness/knowledge`； - 不运行本地 Python ingest、SQLite、FTS 或 context-pack 脚本； - 不在网络或服务不可用时回退到本地归档； - 查询失败只记录“本轮无远端知识”，后续工作必须依靠当前代码和用户提供的信息。 所有面向人的总结默认使用中文，代码标识符和原始路径保持原样。 ## Triggers - query knowledge / knowledge query - 查询历史需求、决策或实现经验 - 结合之前做过的内容 - 规划或排查前读取项目知识 ## Command 在项目根目录执行一次： ```powershell powershell.exe -Command "npx hunter-harness knowledge query '<用户需求原文>' --limit 10 --json" ``` 只允许通过 CLI 访问平台，不得直接拼接 HTTP 请求，也不得调用旧的 本地知识查询脚本（该脚本已从当前分发包移除）。 ## Workflow 1. 原样保留用户的需求或问题作为查询文本；已知范围较大时可将关键模块名一并放入文本。 2. 执行一次远端查询，不在查询前重建或同步知识。 3. 读取 JSON 中的命中项、来源路径、变更键和相关度。 4. 把命中内容作为历史线索；涉及当前行为时仍以当前代码和验证结果为准。 5. 若命令返回远端不可达、未绑定或未认证，记录明确 issue 后继续，不重试本地方案。 ## Output Contract 必须说明： - 查询文本与 limit； - 是否成功访问远端； - 命中数量及最相关来源； - 远端不可用时，明确写“未使用本地回退”； - 下一步是进入规划/实现，还是先核对当前代码。 ## Forbidden Actions - create_local_knowledge_index - query_local_sqlite_or_archive_as_fallback - generate_local_context_pack - retry_with_legacy_python_knowledge_script - treat_remote_history_as_current_code_fact - copy_secrets_into_query ## P0 执行可信度规则 - 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次 - 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN - 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]] ## 生成内容语言约定 - sync/ingest 等生成的文档、规则、知识条目、架构说明一律**优先使用中文**撰写（标识符、命令、代码、API 字段名保持原文） - 面向平台展示的标题/摘要/正文默认中文；仅当用户明确要求或目标系统强制时才用英文 > 片段：p0-trust · 远端查询成功必须有 CLI JSON 证据；失败不得伪装为已读取历史 ## 执行日志 `events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]] **`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的 `phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发 auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。 （重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。） ```powershell # 阶段开始：gate begin 负责，note 在这里给 python /scripts/harness_gate.py begin --change-dir ".harness/changes/" --phase --note "<触发指令>" # 阶段中的其他事件才用 append python /scripts/harness_events.py append --change-dir ".harness/changes/" --phase --type --run-id --note "<摘要>" ``` > **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。 每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt `，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布 plan 的修订通过重跑 `plan evidence-pack` + `plan finalize` 分配新 attempt（`harness_plan_finalize.py republish` 已于 0.3.0 移除）。 阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change --executor ` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--executor-tool `，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。 > 片段：logging · phase=`knowledge-query` · 成功记录命中摘要，失败记录远端错误码且不做本地回退