xuanzhu 0.6.0 → 0.6.1

package/README.md

@@ -34,6 +34,10 @@ xzh                 # 启动
   直到它调用 `goal_complete` 声明完成 —— 中途不需要你再发「继续」（见「目标模式」）。
 - **任务拆分**：3 步以上的复杂任务会先用 `todo_write` 列出计划并逐步更新，
   顶部信息区实时显示进度条（`任务 2/5` 与当前进行项）。
+- **自我状态块**：每轮自动把目标、任务进度、最近动作、改动文件与上下文占用汇总给模型看
+  （由代码生成、只读、不进历史），长任务里不容易「忘了做到哪」；改过文件却没跑验证时会提醒一次。
+- **不确定性通道**：卡住 / 需要你决定 / 没把握时，模型可以结构化上报而不是编结论；
+  目标模式下受阻会暂停并保留目标（见「自我状态与验证门」）。
 - **子代理协作（可并行）**：需要大范围调研（跨多个文件 / 目录 / 命名约定）时，用 `task`
   派生 `code-explorer` 子代理独立完成，**只把结论带回主对话** —— 中间过程不会挤占主上下文；
   改完代码后可派 `test-runner` 跑测试并带回「通过/失败清单 + 失败原因 + 可复跑命令」，
@@ -162,6 +166,9 @@ xzh
 | `xzh config path` | 打印配置文件路径 |
 | `xzh config init` | 生成默认配置文件 |
 | `xzh setup` | 检查并自动安装依赖（玄猪自身 + 技能：playwright / officecli / 剪贴板工具等） |
+| `xzh init` | 扫描项目并生成 / 补全 `AGENTS.md` 与 `docs/`（已有内容只补缺失小节） |
+| `xzh init --dry-run` | 只预览将生成的内容，不写文件 |
+| `xzh init --force` | 整体覆盖已有规范文件（覆盖前自动备份） |
 | `xzh skill` | 交互式管理技能：启用 / 禁用 / 删除（禁用的技能对模型不可见） |
 | `xzh skill list` | 列出全部技能（来源与状态，含已禁用项） |
 | `xzh skill enable/disable <名称>` | 启用 / 禁用技能 |
@@ -372,6 +379,7 @@ API Key 也可以来自环境变量，优先级低于配置文件：
 | `memory_compact` | 用精简后的完整内容重写长期记忆（把新结论并入主题小节 / 语义压缩） | 否 |
 | `todo_write` | 创建 / 更新任务列表（每次提交完整列表） | 否 |
 | `goal_complete` | 目标模式（`/goal`）下声明目标已全部完成（仅主代理可用） | 否 |
+| `report_status` | 结构化上报受阻 / 需要用户决定 / 置信度低（仅主代理可用） | 否 |
 | `task` | 派生子代理（默认 `code-explorer`）执行子任务，只返回结论；一轮内多个调用**并行**执行 | 否 |
 | `read_file` | 读取文件（带行号，支持偏移与行数限制） | 否 |
 | `list_dir` | 列出目录内容 | 否 |
@@ -483,6 +491,48 @@ API Key 也可以来自环境变量，优先级低于配置文件：
   仍会弹确认，确认后循环继续；想全程无人值守请先 `/auto on`。
 - `/reset`、`/resume`、`/switch` 会清掉当前目标（它们替换了目标所依赖的对话上下文）。
 
+## 自我状态与验证门
+
+每次请求都会附带一段**由代码生成**的只读状态（不额外调用模型、不写入对话历史）：
+
+```
+[当前状态 · 系统根据确定事实生成，仅供参考，不要复述]
+- 目标：重构区间策略（进行中 · 已用 12m）
+- 任务：2/5 完成；进行中：修 server.py 重复路由；待办：跑回测
+- 状态：受阻 —— 缺少 BTC_API_KEY
+- 最近动作：read_file ✓、edit_file ✓、bash ✗
+- 本次会话已改动：client/api/server.py
+- 上下文：约 62%（较早内容可能已被裁剪）
+```
+
+它解决的是长任务里最常见的问题——模型「忘了自己做到哪了」，于是重复劳动或提前收尾。
+内容全部来自代码掌握的事实，不靠模型自述；没有任何内容时不会生成，不占额外 token。
+
+**收尾检查（验证门 + 未完成门）**：模型准备结束本轮时，代码会检查两件事，并**合并成一条**提醒
+（每次对话最多一次，第二次仍直接答复就尊重它的判断）：
+
+- **验证门**：本轮改过文件（`write_file` / `edit_file`）却一次验证命令都没运行
+  （测试 / 构建 / 类型检查 / lint，如 `npm test`、`npm run build`、`pytest`、`tsc`、`go test`）
+  → 要求补跑验证，或说明无法验证的原因与风险。先跑验证、之后又改文件仍会提醒（旧验证不覆盖后续改动）。
+- **未完成门**：本轮**自己列过** `todo_write` 计划，且还有 `in_progress` / `pending` 项
+  → 要求继续完成，或说明为什么现在停（受阻 / 需要用户决定 / 有意暂停）。
+  没有 todo 的简单问答不会触发；目标模式下不生效（由 `/goal` 循环负责继续）。
+
+两类问题同时存在时只发一条提示，不会连续打断两次。`bash` 里用 `sed -i` 之类直接改文件不会被追踪，
+这是当前 PoC 的已知边界。
+
+**不确定性通道**：模型可以调用 `report_status` 结构化上报三种情况 ——
+
+| kind | 含义 | 行为 |
+| --- | --- | --- |
+| `blocked` | 外部条件不满足（缺凭据、权限、网络、依赖） | 目标暂停并保留，显示原因；补齐后 `/goal continue` |
+| `needs_input` | 必须由你做出选择 | 同上，暂停并等待你的决定 |
+| `low_confidence` | 还能继续，但结论没把握 | 不打断，记入状态块，答复前提醒标注不可靠之处 |
+
+防滥用：目标模式下本轮一次工具都没调用就报 `blocked` / `needs_input`，会被直接拒绝
+（要求先实际尝试）；`low_confidence` 不受限制。`goal_complete` 只用于「真正完成」，
+受阻不再被当成完成。
+
 ## 图片输入（Ctrl+V）
 
 在输入框按 **Ctrl+V**（或 `/image`、`/paste`）会把**系统剪贴板里的图片**加为本轮附件，
@@ -641,6 +691,32 @@ AutoX.js 那侧也可用环境变量 `XZH_DEVICE_PORT` 指定端口。
 
 > 技能与 CLI 为**全局通用**：技能位于 `~/.xzh/skills`（叠加内置），CLI 安装在系统，均不受项目限制。
 
+## 初始化项目规范（`xzh init` / `/init`）
+
+`xzh init` 扫描当前项目，生成 / 补全开发规范。**内容全部来自扫描**（package.json scripts、
+锁文件、Makefile、构建与测试配置、目录结构），**不调用模型**——命令写错比没有规范更危险，
+因为它会被当成权威约定注入后续对话。
+
+| 文件 | 内容 |
+| --- | --- |
+| `AGENTS.md` | 入口级：项目概览、常用命令、两层目录树、开发约定、文档索引（保持精简） |
+| `docs/ARCHITECTURE.md` | 目录结构、模块概览、入口与运行方式；无法确定的部分标注「待补充」 |
+| `docs/COMMANDS.md` | 命令表 + `package.json` scripts 原始内容（有命令时才生成） |
+| `docs/CONVENTIONS.md` | 从配置文件探测到的风格与工程约定（有配置时才生成） |
+
+| 命令 | 说明 |
+| --- | --- |
+| `xzh init` | 生成缺失文件；已存在的文件**按 `##` 小节合并**，只追加缺失小节，保留原内容 |
+| `xzh init --dry-run` | 只打印变更计划与预览，不写任何文件 |
+| `xzh init --force` | 整体覆盖已有规范文件（覆盖前写 `.bak-<时间戳>` 备份） |
+| `xzh init --yes` | 跳过确认（脚本 / CI） |
+| `/init` | 对话内执行（写入前弹确认框；支持 `/init --dry-run`、`/init --force`） |
+
+- **幂等**：再次运行内容无变化时不写盘，只报「已是最新」；
+- **不自动「修正」**：已有同名小节一律保留（不改写团队手写约定），只补缺失部分；
+- **不在进入项目时自动执行**：启动保持只读；需要时手动运行，避免每次启动都扫描、写文件。
+- 已有的 `.xuanzhu/rules.md` 会在项目根存在 `AGENTS.md` 时要求模型严格遵循它，因此生成的规范会直接影响后续对话 —— 请像维护代码一样维护它。
+
 ## 内置技能
 
 技能是一份指导玄猪使用特定外部 CLI 工具的指南（`skills/<name>/SKILL.md`）。
@@ -768,7 +844,7 @@ description: 一句话说明该技能的用途与适用场景
 kitty / Ghostty 会把该 xterm 兼容序列映射成「所有按键都用转义码上报」而破坏普通输入，
 故玄猪对这两类终端不发送请求，请改用 `Alt+Enter` 或在终端侧自行配置。
 
-界面内命令：`/help`、`/clear`、`/tools`、`/device`、`/image`（`/paste`）、`/copy [N|A-B|last|all]`、`/mouse`、`/reset`、`/undo`、`/resume [编号]`、`/cwd`、`/switch <目录>`、`/term`、`/model [编号|id|模型名]`、`/goal <目标>`（`/goal [status|continue|off]`）、`/memory [clear]`、`/auto [on|off]`、`/intent [on|off]`、`/exit`。
+界面内命令：`/help`、`/clear`、`/tools`、`/device`、`/image`（`/paste`）、`/copy [N|A-B|last|all]`、`/mouse`、`/reset`、`/undo`、`/resume [编号]`、`/cwd`、`/switch <目录>`、`/term`、`/model [编号|id|模型名]`、`/goal <目标>`（`/goal [status|continue|off]`）、`/memory [clear]`、`/init [--dry-run|--force]`、`/auto [on|off]`、`/intent [on|off]`、`/exit`。
 
 ### 选中与复制