@michelj/context-guard 0.4.2 → 0.4.4

package/README.zh-CN.md

@@ -2,233 +2,196 @@
 
 语言：[English](README.md) | **中文**
 
-Context Guard 是一个给 Codex 用的项目记忆 skill。它把任务主线、支线、bad case 和验证链路保存在项目自己的 `.codex/context/` 里，让 Codex 在不同 session 之间也能知道“现在做到哪里、踩过哪些坑、下次怎么检查”。
+Context Guard 是一个面向 Codex、Cursor 和 Claude 的项目记忆 skill。它把任务主线、支线、bad case 和验证链路保存在项目自己的 `.codex/context/` 里，让 Agent 在不同 session 之间也能知道“现在做到哪里、踩过哪些坑、下次怎么检查”。
 
 ## 能做什么
 
-- **维护项目 context**：自动创建并更新 `.codex/context/`。
-- **记录路线图**：维护主线、支线、分叉节点和当前进度。
-- **记录 bad case**：保存问题现象、触发条件、原因、修复方式和防复发检查。
-- **生成 Roadmap HTML**：给用户查看清晰的路线图，点击节点看详情。
-- **区分人类视图和 agent 视图**：HTML 给人看，Markdown/JSON 给 Codex 读取。
-- **支持多语言记录**：按项目偏好用中文或英文写 context。
-- **处理任务切换**：遇到新方向、支线任务或中断任务时，帮助 Codex park/resume。
-- **测试由人类设计**：Codex 只复用已确认检查，或提出草案等待用户确认，不静默创建长期测试。
-- **用功能链覆盖 bad case**：优先把多个 bad case 挂到同一条真实功能/工作流测试链上，而不是为每个 bad case 单独造测试。
-- **默认运行已确认测试**：用户创建或确认的测试，默认每次开发结束都要运行；只有用户说明不必每次运行时才降频。
-- **提供测试中台入口**：`dev-complete` 会统一运行已确认的 always-run 测试，成功清理临时产物，失败保留证据。
+- **四块**：会话、坏例、任务、地图，都在当前项目的 `.codex/context/`
+- **首次建图**：人和 Agent 先商量第一层怎么切（可以先给几种拆法或较多候选），定了再拆第二层、第三层。卡名要一眼能看懂。之后会话打开这张图
+- **人看工作台**：`prototype/workbench.html`。Agent 读小索引，不读整张地图
+- **用户原话**：写进 `user-messages.md`；密钥只在 `private/`
+- **记录语言**：按文件夹选中文或英文
+- **生命周期**：首次 Session 自动建档、记录用户消息，并在识别到 bad case 后通过统一命令落盘
 
-## 安装
+第一版**没有** Roadmap HTML、测试中台、功能链。
 
-使用 npx 安装：
+## 工作台
 
-```bash
-npx @michelj/context-guard install
-```
+人在工作台里看图、点头。安装 Hook 后，新 Session 会自动启动本机单实例服务并打开页面；Agent 读 `.codex/context/` 里的小索引，不操作画布。
 
-也可以全局安装，让 npm 包自动把 skill 复制到 Codex 的 skill 目录：
+**当前工作台：** [prototype/workbench.html](https://github.com/Michel-Johnson/Context-Guard-Skill/blob/main/prototype/workbench.html) · [浏览器打开](https://raw.githack.com/Michel-Johnson/Context-Guard-Skill/main/prototype/workbench.html)
 
-```bash
-npm install -g @michelj/context-guard --registry=https://registry.npmjs.org
-```
+第一次打开可能会看到 GitHack 的提示页（它只是中转，没审过页面内容）。点 **Open the page** 就进工作台。
 
-只有当你明确希望安装 Codex 生命周期 hook 提醒时，才加 `--with-hooks`：
+要自己定第一层：顶栏点仓库名，切到 **OpenClaw**（首次使用），点「看几种第一层切法」，选一种才上画布。仍是演示卡名，但切法是你定的。
 
-```bash
-npx @michelj/context-guard install --with-hooks
-```
+顶栏 **中 / EN** 切界面语言。地图上的标题、用途、记忆仍按写入时的语言，不整页翻译。
 
-npm 包正式发布前，也可以直接从 GitHub 使用：
+也可以手动启动或停止工作台：
 
 ```bash
-npx github:Michel-Johnson/Context-Guard-Skill install
+context-guard workbench --root /path/to/project
+context-guard workbench --root /path/to/project --stop
 ```
 
-也支持手动安装：
+### 总览
 
-```bash
-git clone git@github.com:Michel-Johnson/Context-Guard-Skill.git
-cd Context-Guard-Skill
-mkdir -p ~/.codex/skills/context-guard
-rsync -a --delete skills/context-guard/ ~/.codex/skills/context-guard/
-```
+第一页 4–8 张主干模块卡。点一张进入。未修 Bug 在右侧列表。
 
-安装后 Codex 应该能发现：
+![工作台总览](docs/shots/workbench/overview.png)
 
-```text
-~/.codex/skills/context-guard/SKILL.md
-```
+### 进入模块
 
-## Context 保存在哪里
+开工单元挂在模块下面，只画从属实线。
 
-Context 必须保存在当前打开的本地项目里：
+![模块内部](docs/shots/workbench/module.png)
 
-```text
-<Codex 打开的项目根目录>/.codex/context/
-```
+### 模块关系
 
-不要把 context 写到：
+点「关系」再点一张卡，只高亮它的生产/消费，其它变暗，不会进入该模块。
 
-- skill 安装目录
-- chat/thread 名称对应的目录
-- 临时目录
-- SSH 远程服务器路径
+![模块关系](docs/shots/workbench/relations.png)
 
-如果手动运行脚本，建议显式传入项目根目录：
+### 会话流动
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
-```
+点一条挂了会话的 Bug。从根到该节点的链路亮起来，当前会话沿线流动。
+
+![会话流动](docs/shots/workbench/session-flow.png)
+
+### 授权模式
+
+「授权模式」标出这次会话 Agent 能读哪一段。灰色卡未授权。
 
-注册一个用户已确认的自动化测试：
+![授权模式](docs/shots/workbench/auth-mode.png)
+
+## 安装
+
+使用 npx 安装。安装器会检测 Codex、Cursor 和 Claude，把 Skill 与生命周期 Hook 一起安装并安全合并现有配置：
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-add \
-  --root /path/to/project \
-  --title "Markdown 预览渲染" \
-  --command-text "npm test"
+npx @michelj/context-guard install
 ```
 
-注册一条用户已确认的功能链测试：
+也可以全局安装，让 npm 包自动安装到检测到的客户端：
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-add \
-  --root /path/to/project \
-  --title "GPU 监控按钮" \
-  --entry "点击 GPU 监控按钮" \
-  --exit-check "打开包含有效 grafana_url 的监控页" \
-  --command-text "npm test -- gpu-monitor"
+npm install -g @michelj/context-guard --registry=https://registry.npmjs.org
 ```
 
-把 bad case 挂到功能链的具体环节：
+强制安装到三类客户端：
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-attach-bc \
-  --root /path/to/project \
-  --chain-id FC-... \
-  --node-title "后端返回监控 URL" \
-  --bad-case BC-... \
-  --check "grafana_url 不为空，前端不会卡住"
+npx @michelj/context-guard install --platform all
 ```
 
-开发完成后交给测试中台：
+默认会安装 Hook；如果只想复制 Skill，可以显式关闭：
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py dev-complete --root /path/to/project --jobs 2
+npx @michelj/context-guard install --no-hooks
 ```
 
-查看只读测试中台页面：
+默认目录分别是 `~/.codex/skills/context-guard`、`~/.cursor/skills/context-guard` 和 `~/.claude/skills/context-guard`。安装器会备份并合并现有 Hook/Settings；Codex 同时启用 `[features] hooks = true`，并迁移旧的 `codex_hooks` 别名。
+
+npm 包正式发布前，也可以直接从 GitHub 使用：
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-test-hub --root /path/to/project --open
+npx github:Michel-Johnson/Context-Guard-Skill install
 ```
 
-简单管理测试：
+也支持手动安装：
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-list --root /path/to/project
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-disable --root /path/to/project --test-id TC-... --reason "暂时不需要每次运行"
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-enable --root /path/to/project --test-id TC-...
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-set-policy --root /path/to/project --test-id TC-... --run-policy relevant-only --reason "只和编辑器改动相关"
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-remove --root /path/to/project --test-id TC-...
+git clone git@github.com:Michel-Johnson/Context-Guard-Skill.git
+cd Context-Guard-Skill
+mkdir -p ~/.codex/skills/context-guard
+rsync -a --delete \
+  SKILL.md README.md README.zh-CN.md agents prototype references scripts \
+  ~/.codex/skills/context-guard/
 ```
 
-## 常用方式
-
-让 Codex 启用并维护 context：
+安装后相应客户端应该能发现：
 
 ```text
-Use $context-guard to maintain this task context.
+~/.codex/skills/context-guard/SKILL.md
+~/.cursor/skills/context-guard/SKILL.md
+~/.claude/skills/context-guard/SKILL.md
 ```
 
-展示当前路线图：
+## 发布
+
+这个 npm 包不使用 GitHub Release 作为交付入口。用户从 npm 安装 skill，因此正式发布由版本标签驱动：
+
+1. 把 `package.json` 更新到下一个稳定版本，并将该提交合入 `main`。
+2. 在该提交上创建完全匹配的 `vX.Y.Z` 标签。
+3. 推送标签；`.github/workflows/npm-publish.yml` 会校验、打包、安装冒烟，并把同一份 tarball 发布到 npm。
+
+该 workflow 没有手动触发入口。推送匹配的版本标签后，GitHub 会自动执行完整发布流水线；验证通过的 tarball 会作为 GitHub Actions Artifact 保留 14 天。它复用 `Michel-Johnson/Context-Guard-Skill` 已有的 npm Trusted Publisher，workflow 文件名保持 `npm-publish.yml`，允许 `npm publish` 操作；Actions 发布不需要本地登录 npm。完整步骤见 [npm 发布与恢复手册](https://github.com/Michel-Johnson/Context-Guard-Skill/blob/main/docs/npm-release-runbook.md)。
+
+## Context 保存在哪里
+
+Context 必须保存在当前打开的本地项目里（不随客户端改变）：
 
 ```text
-Use $context-guard to show the roadmap.
+<当前项目根目录>/.codex/context/
 ```
 
-初始化项目 context：
+不要把 context 写到：
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py init --root /path/to/project
-```
+- skill 安装目录
+- chat/thread 名称对应的目录
+- 临时目录
+- SSH 远程服务器路径
 
-设置记录语言：
+对后续工作有价值的短用户消息会保存在：
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py set-language --root /path/to/project --language 中文
+```text
+<当前项目根目录>/.codex/context/user-messages.md
 ```
 
-生成路线图：
+如果用户提供了后续需要复用的凭据，Context Guard 只会在公开 context 中记录脱敏指针。原始凭据必须只保存在本地私有目录：
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
+```text
+<当前项目根目录>/.codex/context/private/
 ```
 
-也可以用 npm CLI 作为轻量封装：
+如果手动运行脚本：
 
 ```bash
-npx @michelj/context-guard show-roadmap --root /path/to/project
+python3 scripts/context_guard.py init --root /path/to/project
+python3 scripts/context_guard.py set-language --root /path/to/project --language 中文
 ```
 
-创建支线任务：
+第一次 Session 若 `record_language` 仍为 `unset`，Hook 会要求 Agent 先询问“中文还是 English”，保存后后续 Session 不再重复询问。`workbench` 命令会启动本机服务并返回浏览器地址。
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py create-branch-task \
-  --root /path/to/project \
-  --title "支线任务标题" \
-  --branch "支线名称" \
-  --parent-node NODE-YYYYMMDD-001
-```
+## 常用方式
 
-记录路线图节点：
+```text
+Use $context-guard. 四块：会话、坏例、任务、地图。
+```
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py checkpoint-roadmap-node \
-  --root /path/to/project \
-  --title "给 Codex 看的源标题" \
-  --display-title "给用户看的短标题" \
-  --user-request "用户实际提出的问题" \
-  --progress-summary "当前进展" \
-  --method-summary "采取的方法" \
-  --branch Main \
-  --level major \
-  --outcome "结果"
+python3 scripts/context_guard.py init --root /path/to/project
+python3 scripts/context_guard.py set-language --root /path/to/project --language 中文
+python3 scripts/context_guard.py workbench --root /path/to/project
 ```
 
+运行 `context-guard workbench --root /path/to/project` 看图。
+
 ## 主要文件
 
 ```text
 .codex/context/
-|-- index.md              # 快速索引和当前任务
-|-- roadmap.md            # agent 可读路线图
-|-- bad-cases.md          # bad case 登记表
-|-- preferences.json      # 语言和项目偏好
-|-- roadmap/
-|   |-- roadmap.html      # 用户查看的路线图
-|   |-- roadmap.md        # agent 快速读取版
-|   `-- roadmap.json      # 结构化索引
-|-- tasks/                # 任务级 context
-|-- task-cases/           # 任务导向测试 case
-|-- test-hub/             # 测试注册表、最近结果和失败证据
-`-- bad-case-tests/       # 可复用 bad case 检查脚本
-```
-
-## 使用原则
-
-- 路线图只记录关键进展，不记录每个小动作。
-- 用户看的标题要像人话，不要像实现日志。
-- bad case 要能帮助未来避免复发。
-- 测试设计权属于人类；Codex 可以执行已确认检查，或提出待确认草案。
-- 测试的长期单位优先是功能链：一个明确入口、一段真实流程、多个检查点、覆盖多个 bad case。
-- 新 bad case 优先挂到已有功能链节点；没有匹配功能链时，再提出新的功能链草案。
-- 用户确认的测试默认是 `every-dev-completion`；只有用户要求时，Codex 才能改成其他运行频率。
-- 已确认的自动化测试应进入 `.codex/context/test-hub/registry.json` 或 `.codex/context/test-hub/feature-chains.json`，由 `dev-complete` 统一调度。
-- 测试中台保持简单：一个注册表、一个 `dev-complete` runner、一个最近结果、一个只读 HTML 状态页和几个管理命令。
-- Codex 最终总结必须说明当前测试中台结果：已确认的 always-run 测试是否全部通过、失败、阻塞，或当前没有这类测试。
-- 测试链路优先复用已有命令、脚本、截图或人工检查。
-- 不要为了每个 bad case 都新写脚本。
-- 前端或 HTML 改动结束前，应实际查看页面或截图，确认没有明显视觉错误。
-- 任何新的长期测试 case 都先写简短草案，让用户确认后再变成 active 测试。
-
-详细行为规则见 [`skills/context-guard/SKILL.md`](skills/context-guard/SKILL.md)。
+|-- FIND.md
+|-- sessions.jsonl
+|-- sessions/
+|-- bugs-index.json
+|-- bugs/ 和 fixes/
+|-- tasks/
+|-- map.json
+|-- owns-index.json 和 cards/   # 生成
+|-- preferences.json
+|-- user-messages.md
+`-- private/                     # gitignored
+```
+
+见 [`SKILL.md`](SKILL.md)（一页）和 `.codex/context/FIND.md`。

package/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: context-guard
+description: "Keep folder-scoped project memory: sessions, bugs, tasks, and the architecture map. Use at the start of a folder, when the map or a bug is involved, when direction changes, and during coding/debugging/review."
+---
+
+# Context Guard
+
+Human–agent project memory for Codex, Cursor, and Claude. Hooks activate it; the agent records; the human confirms in the HTML workbench.
+
+## When to use
+
+- First session in this folder, or no live map yet
+- The human asks to open or change the map
+- Direction changes, park/resume, coding, debugging, review
+
+## What to do
+
+Four stores only:
+
+1. **Sessions** — lifecycle hooks append `.codex/context/sessions.jsonl` and create `sessions/{id}.md`
+2. **Bugs** — thin card in `.codex/context/bugs/{id}.md` plus how-to in `fixes/{id}.md`; stub on the map node
+3. **Tasks** — playbook in `.codex/context/tasks/{id}.md`
+4. **Map** — live tree in `.codex/context/map.json`; short memories and ideas stay on the node
+
+How to find a file: read `.codex/context/FIND.md`, then the small indexes (`owns-index.json`, `bugs-index.json`, `tasks-index.json`, last lines of `sessions.jsonl`). Open only the hit Markdown. After the map changes: `python3 scripts/map_owns.py cards`.
+
+Formats: `.codex/context/FORMAT.md`. The SessionStart hook starts the local human workbench and injects its URL.
+
+First session language: when `.codex/context/preferences.json` has `record_language: unset`, ask the user whether project context should be recorded in 中文 or English before substantive project work. Do not infer the answer. Persist it with `context-guard set-language --root <project> --language <zh-or-en>`. Do not ask again after it is set.
+
+First use (no map yet): talk with the human layer by layer. First offer several ways to cut L1, or a larger set of candidate modules whose titles a person can read in seconds. After they lock L1 (about 4–8), design L2, then L3. Write `architecture.md` as you go. Put the agreed L1 into `map.json` with `owns` paths and `map_bootstrap` proposed. Later sessions open that map. Do not dump a full tree, a directory listing, or one node per file.
+
+When a credible failure or user-reported bad case appears, record it immediately with `context-guard record-bad-case --root <project> --title <title> --phenomenon <what-failed> --trigger <trigger> --cause <cause-or-pending> --guard <regression-guard> --node <map-node> --keys <comma-separated>`. Do not create a bad case from a guess.
+
+CLI: `context-guard init`, `set-language`, `workbench`, and `record-bad-case`. People look at the workbench, not a generated roadmap page.
+
+## What not to do
+
+- Do not paste `map.json` or `jump-index.json` into the turn
+- Do not Grep the whole `.codex/context/` tree
+- Do not treat Markdown links as the agent’s hop
+- Do not expand Test Hub, feature chains, Stop-hook gates, or Roadmap HTML
+- Do not write context into the skill install directory, a chat folder, or an SSH remote path
+- Do not put secrets in git-tracked context; redacted pointer only, raw values in `.codex/context/private/`
+- Do not keep a second bad-case register in `bad-cases.md`
+- Do not invent Test Hub scripts

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Context Guard"
+  short_description: "Keep folder-scoped project memory"
+  default_prompt: "Use $context-guard. Four stores: sessions, bugs, tasks, map. Jump with FIND.md."