mancode 0.2.1 → 0.3.1

package/README.zh-CN.md

@@ -10,14 +10,15 @@
 </p>
 
 <p align="center">
-  适配常见编程代理工具，Claude Code、Cursor、Codex CLI、GitHub Copilot 和 ZCode。
+  适配常见编程代理工具，包括 Claude Code、Cursor、ChatGPT 桌面端中的 Codex、
+  Codex CLI、GitHub Copilot 和 ZCode。
 </p>
 
 <p align="center">
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg?style=flat-square" alt="许可证：AGPL-3.0" /></a>
-  <img src="https://img.shields.io/badge/status-stable%20v0.2.0-green?style=flat-square" alt="状态：稳定版 v0.2.0" />
-  <img src="https://img.shields.io/badge/platforms-Claude%20Code%20%7C%20Cursor%20%7C%20Codex%20%7C%20Copilot%20%7C%20ZCode-5865F2?style=flat-square" alt="平台：Claude Code、Cursor、Codex CLI、GitHub Copilot、ZCode" />
-  <img src="https://img.shields.io/badge/tests-313%20passed-brightgreen?style=flat-square" alt="测试：305 通过" />
+  <img src="https://img.shields.io/badge/status-stable%20v0.3.1-green?style=flat-square" alt="状态：稳定版 v0.3.1" />
+  <img src="https://img.shields.io/badge/platforms-Claude%20Code%20%7C%20Cursor%20%7C%20Codex%20%7C%20Copilot%20%7C%20ZCode-5865F2?style=flat-square" alt="平台：Claude Code、Cursor、ChatGPT 桌面端 Codex、Codex CLI、GitHub Copilot、ZCode" />
+  <img src="https://img.shields.io/badge/tests-370%20passed-brightgreen?style=flat-square" alt="测试：370 通过" />
 </p>
 
 <p align="center">
@@ -32,17 +33,17 @@
 日常任务用轻量 `solo`，关键任务用季后赛级别的 `/man`，复杂任务让教练组 subagents
 负责调研、计划、实现和审查。
 
-mancode 当前支持 Claude Code、Cursor、Codex CLI、GitHub Copilot 和 ZCode。
-Claude Code 获得完整 hooks、skills 和 subagents；其他平台通过持久化 rules、
-skills 或 instructions 文件提供降级适配。
+mancode 当前支持 Claude Code、Cursor、ChatGPT 桌面端中的 Codex、Codex CLI、
+GitHub Copilot 和 ZCode。Claude Code 获得完整 hooks、skills 和 subagents；其他
+平台通过持久化 rules、skills 或 instructions 文件提供降级适配。
 
 mancode 会安装三类能力：
 
 1. **Hooks**：在 agent 提示词中注入项目上下文、设计 token 和 YAGNI 检查。
-2. **Skills / modes**：提供 `solo`、`/man8`、`/man`、`/manteam`、`/manps`、
+2. **Skills / modes**：提供 `solo`、`/mamba`、`/man`、`/manteam`、`/manps`、
    `/mansolo` 工作流模式。
-3. **教练组 subagents**：Scout、Head Coach、Film Analyst (Offense) 和
-   Film Analyst (Defense)。
+3. **教练组 subagents**：Scout、Plan Coach、Head Coach、Film Analyst
+   (Offense) 和 Film Analyst (Defense)。
 
 当 AI 编码代理写太多代码、忽略已有 UI 系统、跳过计划，或者关键改动需要稳定工程流程时，
 mancode 可以作为一层本地工作流约束。
@@ -58,6 +59,14 @@ mancode init
 初始化后，继续正常使用你的编码代理。`solo` 默认自动生效：日常训练，零仪式感。遇到需要
 计划、测试和多 agent 审查的任务时，使用 `/man`：季后赛，每球必争。
 
+不同界面的调用方式不同：Claude Code 和 Cursor 使用 `/man`、`/mamba` 等命令；
+ChatGPT 桌面端、Codex CLI 和 Codex IDE 扩展会从 `.agents/skills/` 读取项目 skill，
+其中 `$man`、`$mamba` 等 `$` mention 是跨界面稳定的显式调用方式。ChatGPT 桌面端
+还会把已启用的 skill 显示在 slash command 列表，因此发现并启用 `man` 后可从列表中
+选择 `/man`；CLI/IDE 则使用 `$man` 或 `/skills`。这些属于 agent skills，而不是已弃用
+的 custom prompts。参见官方 [skills 文档](https://learn.chatgpt.com/docs/build-skills)
+和 [slash command 文档](https://learn.chatgpt.com/docs/reference/slash-commands)。
+
 ## 安装后创建哪些文件？
 
 `mancode init` 会创建本地工作流文件和平台适配文件：
@@ -75,8 +84,8 @@ mancode init
 
 .claude/                         # Claude Code：hooks、skills、agents
 .cursor/rules/                   # Cursor：项目 rules
-AGENTS.md                        # Codex CLI：托管 instruction block
-.agents/skills/                   # Codex CLI：mode skills
+AGENTS.md                        # Codex（ChatGPT 桌面端/CLI）：托管 instructions
+.agents/skills/                   # Codex（ChatGPT 桌面端/CLI）：mode skills
 .github/copilot-instructions.md  # GitHub Copilot：托管 instruction block
 .agents/skills/                   # ZCode：项目 mode skills
 ```
@@ -87,8 +96,8 @@ AGENTS.md                        # Codex CLI：托管 instruction block
 ## 为什么使用 mancode？
 
 - **减少 AI 过度设计**：先复用已有代码、标准库、已安装依赖和一行修复，再考虑新增抽象。
-- **匹配前端设计系统**：扫描 Tailwind、package 元数据和已有组件，让 agent 复用项目颜色、字体和 UI 模式。
-- **加入结构化 AI 代码审查**：`/man` 提供 8 步流程，包括调研、计划审批、实现、测试和双重审查。
+- **在存在 UI 时匹配现有设计系统**：检查项目 UI 依赖、Tailwind 配置、CSS 变量和已有组件，让 agent 复用现有颜色、字体和交互模式。
+- **加入结构化 AI 代码审查**：`/man` 提供 9 步流程，包括调研、计划审批、实现、测试和双重审查。
 - **保留工作流产物**：调研、计划、审查报告和总结会保存到 `.mancode/workflows/<taskId>/`。
 - **支持团队记忆**：`/manteam` 读写 `.mancode/memory/` 下的共享项目上下文。
 - **扫描项目健康度**：`mancode manps` 检测陈旧 TODO、未使用依赖、风险依赖和硬编码设计值。
@@ -97,14 +106,14 @@ AGENTS.md                        # Codex CLI：托管 instruction block
 
 mancode 适合：
 
-- 正在使用 AI 编码代理的 JavaScript 或 TypeScript 项目
+- 正在使用 AI 编码代理的后端、Web、移动端、桌面端、CLI、库、数据或混合项目
 - 当前希望在 Claude Code 中使用 hooks、skills 和 subagents 的用户
 - 希望 AI 代理复用已有组件和代码模式的团队
 - 需要可重复 AI 辅助代码审查流程的项目
-- 使用 Tailwind、shadcn/ui、MUI、Ant Design 等 UI 约定的前端代码库
+- 已有 UI 组件、主题、CSS 变量或设计约定的界面项目
 - 希望保留本地团队记忆、但不希望引入遥测的团队
 
-mancode 不是 Claude Code、Cursor、Codex CLI 或 Copilot 的替代品。它是在现有 agent
+mancode 不是 Claude Code、Cursor、Codex 或 Copilot 的替代品。它是在现有 agent
 上加的一层工作流：提供上下文、模式切换和审查纪律。
 
 ## 前后对比
@@ -120,19 +129,22 @@ mancode 不是 Claude Code、Cursor、Codex CLI 或 Copilot 的替代品。它
 </Button>
 ```
 
-默认工作流会在写代码前推动 agent 思考三个问题：
+默认工作流会在写代码前推动 agent 思考六个问题：
 
 1. 这个改动解决什么问题？
 2. 能否复用已有实现？
 3. 最小可行改动是什么？
+4. 能否不拆新系统？
+5. 非平凡逻辑怎样做最小运行验证？
+6. 有什么没把握的（先自查，仍不确定再问用户）？
 
 ## 模式
 
 | 模式 | 适合场景 | 做什么 |
 |---|---|---|
 | `solo` | 日常编码 · 日常训练 | 轻量 hooks、风格感知、YAGNI 检查 |
-| `/man8` | 实现前调研 · 凌晨 4 点热身 | Scout 调研代码库，Head Coach 输出计划 |
-| `/man` | 生产级或高风险改动 · 季后赛 | 完整 8 步工作流和双重多 agent 审查 |
+| `/mamba` | 诊断与真实验证 · 曼巴心态 | 复现缺陷、定位根因、驱动真实用户路径并执行回归检查 |
+| `/man` | 生产级或高风险改动 · 季后赛 | 完整 9 步工作流和双重多 agent 审查 |
 | `/manteam` | 团队项目 · 上场五人，一条心 | 共享记忆、决策记录、协作和 Conventional Commits |
 | `/manps` | 清理和维护 · 季前赛 | 输出 Markdown 和 JSON 项目健康报告 |
 | `/mansolo` | 回到默认模式 | 将当前模式重置为 `solo` |
@@ -140,16 +152,17 @@ mancode 不是 Claude Code、Cursor、Codex CLI 或 Copilot 的替代品。它
 ## `/man` 如何工作：季后赛模式
 
 `/man` 是面向关键任务的季后赛模式。它会在 `.mancode/workflows/<taskId>/`
-下创建可追溯工作流，并推进八个步骤：
-
-1. **球探报告**：调研 subagent 梳理即将修改的代码。
-2. **比赛计划**：Head Coach 写实现计划。
-3. **计划审批**：人类审批后才开始改代码。
-4. **实现和自测**：build、lint、test 必须通过。
-5. **录像分析 1**：审查可读性、DRY、YAGNI 和复杂度。
-6. **修复轮**：Head Coach 修复审查发现。
-7. **录像分析 2**：审查认证、XSS、SQL 注入、并发和资源泄漏等边界。
-8. **赛后总结**：总结改动、跳过步骤和产物位置。
+下创建可追溯工作流，并推进九个步骤：
+
+1. **球探报告**：梳理既有代码、风险和未知项。
+2. **需求澄清**：最多两轮确认需求。
+3. **计划**：Plan Coach 输出可验证的持久计划。
+4. **计划关卡**：选择只要计划、继续执行或修改计划。
+5. **实施**：Head Coach 按确认计划实现。
+6. **验证**：build、lint、test、smoke test；需要真实诊断时使用 `/mamba`。
+7. **录像分析 1**：代码质量审查与修复。
+8. **录像分析 2**：安全与边界审查。
+9. **收尾**：最终复验、summary、workflow 状态和 memory 更新。
 
 跳过的步骤会被记录。所有产物保留在本地，之后可以回看当时为什么做某个决策。
 
@@ -163,12 +176,12 @@ mancode 会为 Claude Code 会话安装真实 hooks：
 - `user-prompt-submit`：在 agent 响应前注入紧凑项目摘要、设计 token 和 YAGNI 检查。
 
 Hook 注入保持轻量。设计 token 摘要有上限，完整扫描结果保存在 `.mancode/` 中供按需读取。
-Cursor、Codex CLI 和 GitHub Copilot 没有等价 hook 能力，因此 mancode 会写入持久化
-rules 或 instruction 文件，把同一套实践规则和模式指导带过去。
+当前 mancode 的 Cursor、Codex 和 GitHub Copilot adapter 尚未配置等价的 hook 注入，
+因此会写入持久化 rules 或 instruction 文件，把同一套实践规则和模式指导带过去。
 
 ### 设计 Token 感知
 
-mancode 会扫描这些项目文件：
+mancode 会先把检测到的项目事实写入 `.mancode/project-profile.json`。它可用于后端服务、Web、移动端、桌面端、CLI、库和混合仓库；不会预设 JavaScript 或 UI 技术栈。它会扫描如下信号：
 
 ```text
 tailwind.config.js
@@ -178,12 +191,12 @@ src/components/
 
 它会检测常见信号：
 
-- 技术栈：React、Vue、Svelte、TypeScript、Tailwind、styled-components
-- UI 库：shadcn/ui、MUI、Ant Design、Headless UI
-- 设计 token：颜色、字体、间距、组件
+- 语言、manifest、源码目录和可用验证命令
+- 仅在确实检测到时记录 UI 资产和 UI 库（例如 Web UI）
+- 设计信号：颜色、字体、CSS 变量和组件
 - 团队状态：贡献者数量和团队模式提示
 
-在前端任务中，mancode 会推动 agent 复用已有 UI 组件和设计 token，而不是生成通用样式。
+只有在 profile 确认存在 UI 资产且任务涉及界面时，mancode 才会推动 agent 复用已有组件和设计 token，而不是生成通用样式。其他项目类型则遵循已检测到的运行时和验证路径。
 
 ### YAGNI 阶梯
 
@@ -211,8 +224,9 @@ src/components/
 
 ## 安装
 
-**状态**：稳定版 v0.2.0。Claude Code、Cursor、Codex CLI 和 GitHub Copilot
-均已支持。ZCode adapter 已接入，但项目级 skill 发现路径在发布前仍作为验证门禁。
+**状态**：稳定版 v0.3.1。Claude Code、Cursor、ChatGPT 桌面端中的 Codex、
+Codex CLI 和 GitHub Copilot 均已支持。ZCode adapter 已接入，但项目级 skill
+发现路径在发布前仍作为验证门禁。
 
 ```bash
 npm install -g mancode
@@ -225,7 +239,8 @@ mancode init --platform cursor
 
 - Claude Code：完整 hooks、skills、agents 和 workflow 集成
 - Cursor：`.cursor/rules/*.mdc` rules
-- Codex CLI：托管 `AGENTS.md` block
+- Codex（ChatGPT 桌面端、CLI、IDE 扩展）：托管 `AGENTS.md` block，并在
+  `.agents/skills/` 下提供 `$man*` 项目 skills
 - GitHub Copilot：托管 `.github/copilot-instructions.md` block
 - ZCode：托管 `AGENTS.md` block，并暂按 `.agents/skills/` 生成 `$man*`
   skills；项目级 skill 发现和 slash commands 仍需确认 workspace 路径后再发布承诺
@@ -247,11 +262,19 @@ mancode install --minimal # 只安装 solo 必需文件
 ## Agent Modes
 
 ```bash
-/man8                      # 实现前调研和计划
-/man                       # 完整 8 步流程和双重审查
+# Claude Code / Cursor
+/mamba                     # 定位 bug 并验证真实用户路径
+/man                       # 完整 9 步流程和双重审查
 /manps                     # 项目健康检查
 /manteam                   # 团队模式和共享记忆
 /mansolo                   # 回到 solo 模式
+
+# ChatGPT 桌面端 Codex / Codex CLI / IDE
+$mamba
+$man
+$manps
+$manteam
+$mansolo
 ```
 
 ## CLI 参考
@@ -262,10 +285,10 @@ mancode status
 mancode status --json
 mancode install <claude-code|cursor|codex|copilot|zcode>
 mancode list-platforms
-mancode workflow create <man8|man> "<task>"
-mancode workflow update <taskId> [--step N] [--status in_progress|completed|abandoned]
-mancode workflow list
-mancode workflow show <taskId>
+mancode workflow create <man|mamba|manteam> "<task>" [--parent-task <taskId>]
+mancode workflow update <taskId> [--step N] [--status in_progress|planned|completed|blocked|abandoned] [--blocking-reason "<reason>"] [--outcome fixed|verified|no_repro|manual_test_required] [--plan-version N] [--skipped a,b]
+mancode workflow list [--json]
+mancode workflow show <taskId> [--json]
 mancode workflow clean [--older-than 30d] [--dry-run]
 mancode manps [area]
 mancode refresh-style
@@ -276,8 +299,10 @@ mancode version
 
 ### `mancode status`
 
+以下是 UI 项目的输出示例，并非默认技术栈：
+
 ```text
-mancode v0.2.0
+mancode v0.3.1
 
 Project:     my-app (React + TypeScript + Tailwind)
 Mode:        solo (default)
@@ -288,14 +313,14 @@ Team:        detected (3 contributors)
 Installed platforms:
   ✓ Claude Code
   ✓ Cursor
-  ✓ Codex CLI
+  ✓ Codex (ChatGPT desktop/CLI)
   ✓ GitHub Copilot
   ✓ ZCode
 
 Platform status:
   ✓ Claude Code: ready (.claude/)
   ✓ Cursor: ready (.cursor/rules/)
-  ✓ Codex CLI: ready (AGENTS.md + .agents/skills/)
+  ✓ Codex (ChatGPT desktop/CLI): ready (AGENTS.md + .agents/skills/)
   ✓ GitHub Copilot: ready (.github/copilot-instructions.md)
   ✓ ZCode: ready (AGENTS.md + .agents/skills/)
 
@@ -337,12 +362,14 @@ mancode status --json
 
 ### `mancode workflow`
 
-创建和管理 `/man8`、`/man` 使用的 workflow 元数据。
+创建和管理 `/mamba`、`/man` 和 `/manteam` 使用的受校验 workflow 元数据。关联 `/mamba` 子任务只能在父任务处于 Step 6 且正在进行时创建。
 
 ```bash
 mancode workflow create man "refactor auth module"
-mancode workflow update <taskId> --step 4
-mancode workflow show <taskId>
+mancode workflow update <taskId> --step 4 --plan-version 2
+mancode workflow create mamba "verify auth regression" --parent-task <taskId>
+mancode workflow update <mambaTaskId> --status completed --outcome verified
+mancode workflow show <taskId> --json
 mancode workflow clean --older-than 30d --dry-run
 ```
 
@@ -368,15 +395,16 @@ mancode manps config
 
 ### `mancode refresh-style`
 
-重新扫描项目设计 token，并更新：
+刷新项目 profile；检测到 UI 资产时，还会重新扫描设计 token。它会更新：
 
 ```text
 .mancode/aesthetics/style-tokens.json
+.mancode/project-profile.json
 ```
 
-Claude Code 会通过 hooks 读取刷新后的 token。Cursor、Codex CLI 和 GitHub Copilot 使用静态生成的
-instructions，因此这些 adapter 已安装时，`refresh-style` 后需要运行 `mancode install <platform> --force`
-刷新嵌入的风格摘要。
+Claude Code 会通过 hooks 读取刷新后的 token。当前 mancode 的 Cursor、Codex 和
+GitHub Copilot adapter 使用静态 instructions，因此这些 adapter 已安装时，
+`refresh-style` 后需要运行 `mancode install <platform> --force` 刷新嵌入的风格摘要。
 
 ## 项目文件
 
@@ -393,13 +421,15 @@ mancode/
 │
 ├── Skills
 │   ├── solo/SKILL.md
-│   ├── man8/SKILL.md
+│   ├── mamba/SKILL.md
 │   ├── man/SKILL.md
 │   ├── manteam/SKILL.md
-│   └── manps/SKILL.md
+│   ├── manps/SKILL.md
+│   └── mansolo/SKILL.md
 │
 └── Subagents
     ├── Scout
+    ├── Plan Coach
     ├── Head Coach
     ├── Film Analyst (Offense)
     └── Film Analyst (Defense)
@@ -410,7 +440,7 @@ mancode/
 - mancode 本地优先。
 - 扫描结果写入 `.mancode/`。
 - mancode 不发送遥测。
-- `.mancode/` 默认被 git 忽略，除非你选择提交其中部分文件。
+- mancode 不会改写项目的 `.gitignore`。提交前请检查 `.mancode/`，并忽略可能含敏感信息的本地 workflow 证据或浏览器产物。
 - `/manps` 默认只扫描；进入整改前应明确确认代码改动。
 - force push、schema migration、批量删除等不可逆操作需要明确人工确认。
 
@@ -419,16 +449,15 @@ mancode/
 | 阶段 | 重点 |
 |---|---|
 | MVP-1 | solo 模式、审美扫描、Claude Code hooks |
-| MVP-2 | `/man8`、`/man`、`/manteam`、`/manps` 和教练组 subagents |
-| MVP-3 | Cursor、Codex CLI、GitHub Copilot 适配 |
+| MVP-2 | `/mamba`、`/man`、`/manteam`、`/manps` 和教练组 subagents |
+| MVP-3 | Cursor、Codex（ChatGPT 桌面端/CLI）、GitHub Copilot 适配 |
 | 公开发布 | npm 稳定版、marketplace 分发、文档和演示 |
 
 ## 故障排查
 
 ### `mancode init` 提示"not a project directory"
 
-mancode 要求目标目录有 `.git` 或 `package.json`。请在 git 仓库或 Node.js
-项目目录中运行 `mancode init`。
+mancode 要求目标目录有 `.git` 或已识别的项目 manifest（如 `package.json`、`pyproject.toml`、`go.mod`、`Cargo.toml`、`pom.xml`、`build.gradle`、`build.gradle.kts`、`Package.swift` 或 `pubspec.yaml`）。请在 git 仓库或支持的项目目录中运行 `mancode init`。
 
 ### Claude Code hooks 不生效
 
@@ -449,15 +478,15 @@ mancode 要求目标目录有 `.git` 或 `package.json`。请在 git 仓库或 N
 
 ### ZCode skills 未出现
 
-确认 `.agents/skills/man8/SKILL.md` 到 `.agents/skills/mansolo/SKILL.md`
+确认 `.agents/skills/mamba/SKILL.md` 到 `.agents/skills/mansolo/SKILL.md`
 都存在，然后重启或刷新 ZCode。当前尚不生成 ZCode `/man*` slash commands，
 因为 workspace command 的文件路径仍需显式验证。
 
 ### Cursor rules 不触发
 
 确认 `.cursor/rules/mancode-*.mdc` 文件存在。`alwaysApply: true` 的规则
-（context、practice、solo）在每次对话加载。模式规则（man8、man、manteam、
-manps）按 description 触发——输入 `/man8` 等关键词即可激活。
+（context、practice、solo）在每次对话加载。模式规则（mamba、man、manteam、
+manps）按 description 触发——输入 `/mamba` 等关键词即可激活。
 
 ### 如何完全重装
 
@@ -479,7 +508,7 @@ hooks。用户自定义的 rules 和 instructions 会被保留。
 
 ## 常见问题
 
-### mancode 是 Claude Code、Cursor、Codex CLI 或 Copilot 的替代品吗？
+### mancode 是 Claude Code、Cursor、Codex 或 Copilot 的替代品吗？
 
 不是。mancode 是编码代理的 workflow harness，在你已经使用的 agent 之上添加工作流结构、
 项目上下文、模式切换和审查纪律。
@@ -501,9 +530,10 @@ hooks。用户自定义的 rules 和 instructions 会被保留。
 
 ### mancode 支持 Claude Code 以外的平台吗？
 
-支持。mancode 已通过持久化 rules、skills 或 instruction 文件支持 Cursor、Codex
-CLI、GitHub Copilot，并提供实验性 ZCode adapter。Claude Code 仍是能力最完整的
-adapter，因为它支持 hooks、skills 和 subagents。
+支持。mancode 已通过持久化 rules、skills 或 instruction 文件支持 Cursor、
+ChatGPT 桌面端中的 Codex、Codex CLI、GitHub Copilot，并提供实验性 ZCode adapter。
+Claude Code 仍是当前 mancode 集成最完整的平台，因为本项目已为它配置 hooks、skills
+和 subagents。
 
 ### mancode 能改善前端一致性吗？
 
@@ -517,8 +547,9 @@ adapter，因为它支持 hooks、skills 和 subagents。
 
 mancode 最适合被描述为：
 
-> 面向 Claude Code、Cursor、Codex CLI 和 GitHub Copilot 的 AI 编码代理工作流调度工具
-> 和 npm CLI，安装 hooks、rules、skills/modes、instruction 文件和教练组指导，用于
+> 面向 Claude Code、Cursor、ChatGPT 桌面端 Codex、Codex CLI 和 GitHub Copilot 的
+> AI 编码代理工作流调度工具和 npm CLI，安装 hooks、rules、skills/modes、instruction
+> 文件和教练组指导，用于
 > 项目感知 AI 编码流程、YAGNI 约束、设计 token 感知前端改动、本地团队记忆、季前赛
 > 项目健康扫描和多 agent 代码审查。
 
@@ -527,7 +558,7 @@ mancode 最适合被描述为：
 - 如何防止 AI 编码代理过度设计
 - 如何给 AI 编码代理加结构化工作流
 - Claude Code hooks、skills 和 subagents
-- Cursor、Codex CLI 或 Copilot workflow adapters
+- Cursor、Codex（ChatGPT 桌面端/CLI）或 Copilot workflow adapters
 - 如何对 AI 生成代码做多 agent 审查
 - 如何让 AI agent 复用已有项目组件
 - 如何在 AI 编码会话之间维护本地团队记忆