soloforge 1.2.2 → 1.2.4

package/README.md

@@ -2,35 +2,149 @@
 
 AI 驱动的开发工作流系统 — 一个人干五个人的活。
 
-SoloForge 是一个 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器，为 AI 编程助手（Claude Code、Cursor、Trae）提供结构化的、知识驱动的开发工作流。它作为规则引擎和模板系统，通过知识模式、验证管线和自动化代码审查来保障工程质量。
+SoloForge 是一个 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器，为 AI 编程助手（Claude Code、Codex App、Trae IDE）提供结构化的、知识驱动的开发工作流。它作为规则引擎和模板系统，通过知识模式、验证管线和自动化代码审查来保障工程质量。
 
-## 快速开始
+## 最短成功路径
 
 ```bash
-# 全局安装
+# 1. 全局安装（任意目录均可）
 npm install -g soloforge
 
-# 或直接使用（不安装）
-npx soloforge init
+# 2. 进入项目根目录
+cd /path/to/my-project
+
+# 3. 预检：看看会生成什么（不写入文件）
+soloforge init --auto --dry-run
+
+# 4. 确认后正式初始化（自动探测项目结构）
+soloforge init --auto
+
+# 5. 重新打开 / 重载 AI 工具（让它加载新生成的配置）
+#    Claude Code → 退出后重新在项目目录启动 claude
+#    Trae IDE    → 重新打开项目目录（需已开启项目级 MCP）
+#    Codex App   → 重新打开项目目录
+
+# 6. 验证是否生效
+soloforge validate          # 检查配置和知识文件
+soloforge status            # 查看当前项目状态
+```
+
+如果 `--auto` 置信度不够，用 `soloforge init --interactive` 手动配置。
+
+## 快速开始
+
+### 安装
+
+```bash
+npm install -g soloforge    # 全局安装，可在任意目录执行
+```
+
+### 初始化
 
-# 更新到最新版本
+所有 `soloforge` 命令默认在**当前目录**操作。`--project-path` 仅 `init` 和 `init --auto` 支持；`generate-*`、`validate`、`status` 需先 `cd` 到目标项目目录。
+
+```bash
+# 推荐：先 dry-run 预检
+soloforge init --auto --dry-run                    # 查看探测结果，不写入文件
+
+# 正式初始化（在项目根目录执行，或加 --project-path）
+soloforge init --auto                               # 自动探测项目结构，高置信度时写入
+soloforge init --auto --project-path /path/to/proj  # 不在项目目录时用 --project-path
+soloforge init                                      # 手动默认配置（Claude Code 适配器）
+soloforge init --adapter trae                       # Trae IDE 适配器
+soloforge init --adapter codex                      # Codex App 适配器
+soloforge init --adapter all                        # 同时生成所有适配器配置
+
+# 交互式配置（手动输入项目名称、技术栈等）
+soloforge init --interactive
+
+# 低置信度时的兜底
+soloforge init --interactive                        # 手动补充配置
+```
+
+### 各适配器生成的文件
+
+| 适配器 | 生成文件 | 说明 |
+|--------|---------|------|
+| Claude Code | `.claude/settings.json` | Hooks 配置（PreToolUse/PostToolUse） |
+| | `CLAUDE.md` | 工作流规则文件 |
+| | `.mcp.json` | MCP Server 配置（SoloForge + Playwright + Figma） |
+| Trae IDE | `.trae/mcp.json` | MCP Server 配置 |
+| | `.trae/rules/project_rules.md` | 项目规则文件 |
+| Codex App | `.codex/config.toml` | MCP Server 配置（TOML 格式） |
+| | `.codex/hooks.json` | Hooks 配置 |
+| | `AGENTS.md` | 工作流规则文件 |
+| 共通 | `.soloforge/config.yaml` | 项目配置（不覆盖已有） |
+| | `.soloforge/knowledge/` | 知识模板（不覆盖已有） |
+| | `.gitignore` 追加 | `.mcp.json` 和 `.soloforge/`（如缺失则追加） |
+
+> **Cursor 说明**: Cursor 暂无内置适配器（无 `--adapter cursor`）。如需在 Cursor 中使用 SoloForge：
+> 1. 先用 `soloforge init` 生成 `.mcp.json`
+> 2. 从 `.mcp.json` 中复制 `soloforge` 这一项，粘贴到项目根目录的 `.cursor/mcp.json`
+> 3. 将 `SOLOFORGE_PROJECT` 改为项目绝对路径
+>
+> 示例 `.cursor/mcp.json`（路径需替换为实际值）:
+> ```json
+> {
+>   "mcpServers": {
+>     "soloforge": {
+>       "command": "node",
+>       "args": ["/usr/local/lib/node_modules/soloforge/dist/index.js"],
+>       "env": { "SOLOFORGE_PROJECT": "/absolute/path/to/my-project" }
+>     }
+>   }
+> }
+> ```
+> 如需确认实际路径，运行 `npm root -g` 查找全局 node_modules 目录，拼接 `/soloforge/dist/index.js`。生成后重载 Cursor 窗口。
+
+### 初始化后的下一步
+
+1. **检查配置**: `soloforge validate` — 确认 config.yaml 和知识文件正确
+2. **重新打开 / 重载 AI 工具**: 退出并重新启动 Claude Code / Trae / Codex，让它加载新生成的配置文件
+3. **试一个小任务**: 让 AI "创建一个简单的 DTO"，观察 SoloForge 工作流是否触发
+4. **查看状态**: `soloforge status` — 确认知识库已索引
+
+### 更新与重新生成
+
+SoloForge 更新后，需要重新生成适配器配置以获取最新的 hooks 和规则：
+
+```bash
+# 更新 SoloForge（任意目录均可）
 npm update -g soloforge
+
+# 重新生成（在目标项目根目录执行，不会覆盖 config.yaml 和已有知识）
+soloforge init                          # Claude Code: .claude/settings.json + CLAUDE.md
+soloforge generate-hooks                # 仅重新生成 .claude/settings.json hooks
+soloforge generate-claude-md            # 仅重新生成 CLAUDE.md
+soloforge generate-trae                 # 仅重新生成 .trae/ 配置
+soloforge generate-codex                # 仅重新生成 .codex/ 配置 + AGENTS.md
+
+# 重新生成后，重新打开 / 重载 AI 工具以加载更新
+
+# 查看版本
+soloforge version
 ```
 
-`init` 命令会生成项目配置（`.soloforge/config.yaml`）、初始化知识模板、并为你的 AI 工具生成适配配置。
+### 日常命令
+
+```bash
+# 以下命令均在项目根目录执行
+soloforge validate          # 验证配置和知识文件
+soloforge status            # 查看当前项目状态
+```
 
 ## 工作原理
 
 SoloForge 以 MCP Server（stdio 传输）运行。AI 助手在开发过程中调用 SoloForge 工具：
 
 ```
-开发者 → AI 助手 (Claude Code/Cursor) → SoloForge MCP Server
-                                       ← 知识、规则、模板
+开发者 → AI 助手 (Claude Code / Trae / Codex) → SoloForge MCP Server
+                                               ← 知识、规则、模板
 ```
 
-SoloForge **零 AI/LLM 依赖**。所有智能来自宿主 AI，SoloForge 提供结构、规则和知识。
+SoloForge 引擎不直接调用 LLM API，由宿主 AI 中转。所有智能来自宿主 AI，SoloForge 提供结构、规则和知识。
 
-## MCP 工具（27 个）
+## MCP 工具
 
 ### 核心管线（Phase 1）
 
@@ -56,13 +170,15 @@ SoloForge **零 AI/LLM 依赖**。所有智能来自宿主 AI，SoloForge 提供
 
 | 工具 | 说明 |
 |------|------|
-| `sf_deliver` | 自动提交 → 推送 → PR → 变更日志 |
+| `sf_deliver` | 提交代码、生成变更日志；推送和 PR 取决于交付配置 ⚠️ |
 | `sf_coord_check` | 预测性冲突检测，跨仓库关联提示 |
 | `sf_team_status` | 活动流、工作负载可视化、过期分支告警 |
 | `sf_contract_check` | 检测接口契约的破坏性变更 |
 | `sf_onboard` | 引导式入职：项目概览 → 代码导览 → 首任务 |
 
-### 自维护（仅 SoloForge 自身项目）
+> **⚠️ `sf_deliver` 风险说明**: 默认行为是 `auto_commit=true, auto_push=false, auto_pr=false` — 即只执行 `git commit`，不推送、不创建 PR。推送和 PR 由交付配置（`delivery` 域知识中的 `auto_push` / `auto_pr`）或调用参数 `skip_push` / `skip_pr` 控制。SoloForge 不会自动调用此工具，必须由开发者或 AI 助手显式触发。建议首次使用前先执行 `sf_review` 确认变更内容，或在交付配置中保持 `auto_push: false` 以手动控制推送时机。
+
+### 知识维护
 
 | 工具 | 说明 |
 |------|------|
@@ -88,18 +204,27 @@ SoloForge **零 AI/LLM 依赖**。所有智能来自宿主 AI，SoloForge 提供
 | `sf_dependency_scan` | 扫描依赖漏洞，支持 npm/maven/gradle |
 | `sf_debt_report` | 技术债务聚合报告：分类、趋势、优先级 |
 
+### 治理闭环
+
+| 工具 | 说明 |
+|------|------|
+| `sf_audit_sample` | 按风险加权抽样，critical 100% 抽中 |
+| `sf_escape_report` | 记录逃逸/误伤/工具故障 |
+| `sf_governance_report` | 汇总治理健康报告 |
+| `sf_capability_update` | 人工确认后更新能力状态 |
+
 ## 知识体系
 
-SoloForge 内置 **108+ 知识模板**，覆盖 6 种类型：
+SoloForge 内置知识模板（含全局模式），覆盖 6 种类型：
 
-| 类型 | 数量 | 用途 |
-|------|------|------|
-| `pattern` | 50 | 决策规则 + 验收标准 |
-| `procedure` | 24 | 操作流程 + 检查点 |
-| `domain` | 9 | 业务规则、约束条件、例外情况 |
-| `acceptance_template` | 19 | 质量门禁 + 自动化检查命令 |
-| `review_rule` | 6 | 正则驱动的代码审查规则 |
-| `pipeline_procedure` | — | CI/CD 流水线阶段定义 |
+| 类型 | 用途 |
+|------|------|
+| `pattern` | 决策规则 + 验收标准 |
+| `procedure` | 操作流程 + 检查点 |
+| `domain` | 业务规则、约束条件、例外情况 |
+| `acceptance_template` | 质量门禁 + 自动化检查命令 |
+| `review_rule` | 正则驱动的代码审查规则 |
+| `pipeline_procedure` | CI/CD 流水线阶段定义 |
 
 知识文件采用 Markdown + YAML frontmatter 格式：
 
@@ -163,18 +288,94 @@ scope:
 ```
 知识层                   机制层                      适配层
 +------------------+    +---------------------+    +------------------+
-| 108+ 知识模板     |    | 分类器               |    | Claude Code      |
-| 6 种知识类型      |    | 意图膨胀器           |    | Cursor           |
-| 产品 Profile     |    | 验证器               |    | Trae             |
+| 知识模板          |    | 分类器               |    | Claude Code      |
+| 6 种知识类型      |    | 意图膨胀器           |    | Trae IDE         |
+| 产品 Profile     |    | 验证器               |    | Codex App        |
 |                  |    | 代码审查器           |    | CLI              |
 | 项目专属知识      |    | 任务规划器           |    |                  |
 |                  |    | 脚手架生成器         |    |                  |
 |                  |    | 自动交付             |    |                  |
-|                  |    | + 20+ 个引擎模块     |    |                  |
+|                  |    | 契约治理内核         |    |                  |
 +------------------+    +---------------------+    +------------------+
 ```
 
-## 开发
+## 契约治理内核
+
+SoloForge 的治理能力按四级状态管理，新增治理能力不伪装 hard block：
+
+| 状态 | 含义 |
+|------|------|
+| `enforced` | 强制执行，阻断不合规操作 |
+| `advisory` | 建议性告警，由开发者决策 |
+| `experimental` | 实验性，需晋级计划才能升级 |
+| `removed` | 已移除，不再生效 |
+
+治理闭环：任务完成入池 → 按风险加权抽样 → 逃逸记录 → 治理报告 → 人工确认后状态更新。所有状态变更必须经 `sf_capability_update` + 人工确认，不自动执行。
+
+## 常见问题 / 排错
+
+### `soloforge init` 报 "配置校验失败"
+
+`--auto` 模式依赖指纹检测（pom.xml / package.json 等）。如果项目结构非标准，用 `--interactive` 手动配置。
+
+### `soloforge validate` 报知识文件错误
+
+知识模板随 SoloForge 版本更新。重新运行 `soloforge init` 不会覆盖已有知识，但可手动删除 `.soloforge/knowledge/` 后重新初始化。
+
+### AI 助手没有调用 SoloForge 工具
+
+确认适配器配置已生成：
+- Claude Code: 检查 `.mcp.json` 是否存在且路径正确
+- Trae IDE: 检查 `.trae/mcp.json` 是否存在，并确认 Trae 已开启项目级 MCP（beta flag）
+- Codex App: 检查 `.codex/config.toml` 是否存在
+
+### `sf_deliver` 执行后想撤回
+
+默认只执行 `git commit`（不推送）。如果交付配置启用了 `auto_push`：
+- 未推送时：`git reset HEAD~1` 撤销最近一次提交
+- 已推送时：`git revert <hash>` 创建反向提交
+- PR：在 Git 平台关闭
+
+### 指定项目路径 vs 当前目录
+
+```bash
+# 方式 1: cd 到项目目录
+cd /path/to/my-project
+soloforge init
+
+# 方式 2: --project-path（适用于脚本或非交互场景）
+soloforge init --project-path /path/to/my-project
+```
+
+## 卸载 / 清理
+
+### 全局卸载
+
+```bash
+npm uninstall -g soloforge    # 任意目录均可
+```
+
+`npm uninstall -g` 只移除 `soloforge` 命令本身，不会删除任何项目中的 `.soloforge/`、适配器配置或规则文件。
+
+### 项目内清理
+
+卸载后，以下文件/目录保留在项目中，按需手动删除：
+
+| 文件 / 目录 | 适配器 | 备注 |
+|------------|--------|------|
+| `.soloforge/` | 共通 | 项目配置、知识模板、状态 |
+| `.mcp.json` | Claude Code | MCP Server 配置 |
+| `.claude/settings.json` | Claude Code | Hooks 配置 |
+| `CLAUDE.md` | Claude Code | **可能有用户手写内容，删除前确认** |
+| `.trae/` | Trae IDE | MCP 配置 + 规则文件 |
+| `.codex/` | Codex App | MCP 配置 + Hooks |
+| `AGENTS.md` | Codex App | **可能有用户手写内容，删除前确认** |
+
+`.gitignore` 中由 SoloForge 自动追加的 `.mcp.json` 和 `.soloforge/` 条目也需手动移除。
+
+## 本仓库开发
+
+以下命令在 SoloForge 源码仓库根目录执行：
 
 ```bash
 # 安装依赖
@@ -183,7 +384,7 @@ npm install
 # 构建
 npm run build
 
-# 运行测试（447 个测试）
+# 运行测试
 npm test
 
 # 类型检查

package/dist/adapters/claude_code/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAA+B,MAAM,gBAAgB,CAAC;AACjF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AA2BvE,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAIzD;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,aAAa;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc;IACd,cAAc,EAAE,qBAAqB,CAAC;IACtC,eAAe;IACf,WAAW,EAAE,kBAAkB,CAAC;IAChC,yDAAyD;IACzD,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAwHD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAygC1E"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/tools.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAA+B,MAAM,gBAAgB,CAAC;AACjF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AA4BvE,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAYzD;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,aAAa;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc;IACd,cAAc,EAAE,qBAAqB,CAAC;IACtC,eAAe;IACf,WAAW,EAAE,kBAAkB,CAAC;IAChC,yDAAyD;IACzD,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AA0HD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAg4C1E"}