@research-copilot/plugin 1.1.16 → 1.1.18

package/dist/skills/llm-wiki/workbench/AGENTS.md

@@ -0,0 +1,110 @@
+# llm-wiki-agent Codex 协作规则
+
+## 第一原则
+
+不要考虑时间成本，code is cheap，我们来自于未来。
+
+做方案和实现时，不要为了省事降低标准。优先选择长期正确、可维护、符合产品方向的做法。
+
+## 必读文档
+
+动手前先读 [PRODUCT.md](PRODUCT.md)。它是项目的意图、边界、路线和决策来源。
+
+文档、代码、约定互相冲突时，以 `PRODUCT.md` 为准。若需要改变产品决策，先说明冲突点和建议改法，等作者确认后再改文档和代码。
+
+## Codex 工作方式
+
+每次开始任务前，先给自己定义完成标准：做到什么程度才算完成、需要怎么验证、哪些情况需要停下来找作者确认。
+
+默认直接推进任务，不为了普通实现细节反复询问作者。开始动手前用简短语言说明：
+
+- 打算改哪些文件
+- 为什么这么改
+- 可能影响哪些部分
+- 准备用什么方式验证
+
+只有遇到下面情况才停下来等作者拍板：
+
+- 要新增 npm package、Skill、系统依赖或新的配置来源
+- 要做 `PRODUCT.md` 没规划过的能力
+- 当前阶段验收没过，却需要动下一阶段的代码
+- 发现现有实现和 `PRODUCT.md` 的产品决策冲突
+- 需要修改外部库、用户目录、模型凭证或不可逆数据
+
+## 强约束
+
+1. 不要自由发挥。所有实现都要能对应到 `PRODUCT.md`、阶段设计文档或用户当前请求。
+2. 不主动跳阶段。阶段 N 验收不过，不动阶段 N+1 的代码。
+3. 不凭印象回答事实问题。`pi-agent`、Skill、外部库、浏览器行为、文件格式等事实，能查源码就查源码，能查官方文档就查官方文档。
+4. 不直接修改 `node_modules/`。极端情况下需要补丁时，先说明原因和替代方案。
+5. 不把 API key 或模型凭证写进本项目配置。模型凭证由 `~/.pi/agent/auth.json` 管理。
+6. 不混用包管理器。本项目使用 npm。
+7. 不引入规划外依赖。确实需要时，先问它是否属于 `PRODUCT.md` 已规划范围。
+
+## 验证要求
+
+向作者汇报前，尽一切可能实际验证结果。
+
+- 写代码后至少运行相关检查；能跑全量就跑全量。
+- Web 界面改动要启动应用，打开页面，看渲染，点关键流程。
+- 脚本或接口改动要用代表性输入跑一遍，检查输出。
+- 有明显边界情况时，至少模拟一个边界情况。
+- 发现问题就修，再重新验证。
+
+不要把未经验证的初稿交给作者。只有确认正常，或确实遇到需要作者介入的障碍，才汇报。
+
+## 项目当前阶段
+
+详细进度、阶段验收、commit 表以 `PRODUCT.md` 第 10 节为准（这里只放快速概览，不再自存详细状态，避免两处不同步）。
+
+**阶段 4.5 已合入**（图谱可用性收尾：画布导航 + 点击语义重构 + 搜索/图例 + 节点瘦身）。决策见 ADR-22。
+
+❗ 开发主场在**主仓库 monorepo**（本目录是其 `workbench/` 子目录）：图谱引擎在 `packages/graph-engine/`，`npm run dev` 从 monorepo 根执行。原独立 llm-wiki-agent 仓库已只读归档（处置留品牌阶段，见 ADR-20）。
+
+阶段一 / 二 / 三 / 3.5 / 四 / 4.5 均已完成（详见 PRODUCT.md §10）。
+
+## 关键路径速查
+
+| 类型 | 值 |
+|---|---|
+| 一行启动 | `npm run dev`（从 monorepo 根，并行起前后端）|
+| 后端端口 | `8787` |
+| 前端端口 | `5180`，`strictPort: true` |
+| 知识库默认根 | `~/llm-wiki/` |
+| 外部知识库登记 | `~/.llm-wiki-agent/config.json` |
+| 应用数据 | `~/.llm-wiki-agent/` |
+| 会话目录 | `~/.llm-wiki-agent/sessions/<sha256-of-kb-path>/*.jsonl` |
+| 模型凭证 | `~/.pi/agent/auth.json` |
+| 后端代码 | `workbench/server/`，Hono + pi-coding-agent SDK |
+| 前端代码 | `workbench/web/`，Vite + React + shadcn/ui |
+| 共享图谱引擎 | `packages/graph-engine/`（工作台与 Skill 离线 HTML 同享）|
+
+## 环境要求
+
+Node 版本要求：`>=22.19.0`。
+
+仓库根用 `.mise.toml` / `.nvmrc` 锁定版本。开发和验证时优先使用项目锁定的 Node 版本。
+
+## 恢复上下文
+
+如果作者思路断了，或上下文经过压缩，不要急着问“做到哪里了”。
+
+先读：
+
+1. `PRODUCT.md`
+2. 当前阶段设计文档
+3. git log / git diff
+4. 相关代码和测试
+
+日志和 git 是事实，文档是意图。对照后再继续。
+
+## 对作者汇报
+
+汇报时用简单直白的语言，说清楚：
+
+- 做了什么
+- 结果怎样
+- 怎么验证过
+- 如果有遗留问题，为什么现在不能继续处理
+
+最终回复不要堆实现细节。作者要的是完成、能用的成果，不是中间过程。

package/dist/skills/llm-wiki/workbench/CLAUDE.md

@@ -0,0 +1,54 @@
+# llm-wiki-agent 项目规则
+
+## 第一原则
+
+不要考虑时间成本，code is cheap，我们来自于未来。
+
+## 必读文档
+
+**[PRODUCT.md](PRODUCT.md)** —— 产品定位、架构、5 阶段路线（+ 阶段 3.5 / 4.5）、22 条 ADR、协作规则。任何动手前先读这份文档。
+
+文档与代码 / 约定冲突时，**以 PRODUCT.md 为准**。
+
+## AI 协作规则（强约束）
+
+1. **不要自由发挥**。每次动手前先说"打算改哪些文件、为什么这么改、对其他部分有什么影响"，作者确认后再动。
+2. **新增依赖**（npm package、Skill、配置项）前，先问"这是 PRODUCT.md 里规划过的吗"。规划外的依赖不要先装。
+3. **修改 PRODUCT.md 之外的决策**，先说"这与 PRODUCT.md §X.Y 冲突，建议改文档为 Z"，等作者拍板。
+4. **作者思路断了时**，先读 PRODUCT.md，不要急着问"做到哪里了"——日志 / git 是事实，文档是意图，对照看。
+5. **绝不主动跳阶段**。阶段 N 验收不过，不允许动阶段 N+1 的代码。
+6. **求真不猜**。pi-agent / Skill / 外部库的事实，能查源码就查源码，能查文档就查文档，不要凭训练数据印象答。
+
+## 项目当前阶段
+
+**阶段 4.5 已合入**（图谱可用性收尾：P0 画布导航 + P0 点击语义重构 + P1 搜索/图例 + P2 节点瘦身）。决策：PRODUCT.md ADR-22。
+
+❗ 开发主场已在**主仓库 monorepo**（本目录是其 `workbench/` 子目录）：引擎在 `packages/graph-engine/`，`npm run dev` 从 monorepo 根执行。原独立 llm-wiki-agent 仓库已进入只读过渡状态（不 archive，处置留品牌阶段，见 ADR-20）。
+
+阶段一 / 二 / 三 / 四已完成（详见 PRODUCT.md §10）：
+
+- 阶段一 ✅ 2026-05-26（主干打通）
+- 阶段二 ✅ 2026-05-27（@、/、结晶、消化）
+- 阶段三 ✅ 2026-05-27（5 个导出按钮 + 4 个 vendored anthropics Skills + 产物右抽屉 + HTML iframe + 下载渲染器 + Skill 可见性开关）
+- 阶段 3.5 ✅ 2026-05-27 至 2026-05-28（导航、多模型、批量消化、当前知识库检索、工作台视觉、可调预览、设置面板滚动修复）
+- 阶段四 ✅ 2026-06-12（monorepo 合并 + 共享图谱引擎 + 活地图：钉扎/选区/生长动画 + 离线 HTML 切引擎产物）
+
+## 关键路径速查
+
+| 类型 | 值 |
+|---|---|
+| 一行启动 | `npm run dev`（从仓库根，并行起前后端）|
+| 后端端口 | `8787` |
+| 前端端口 | `5180`（`strictPort: true`）|
+| 知识库默认根 | `~/llm-wiki/` |
+| 外部知识库 | 用户任意路径，登记在 `~/.llm-wiki-agent/config.json` |
+| 应用数据 | `~/.llm-wiki-agent/`（UI 偏好、外部库登记、对话历史、`lastUsedKbPath`；**不存 API key**）|
+| 会话目录 | `~/.llm-wiki-agent/sessions/<sha256-of-kb-path>/*.jsonl` |
+| 模型凭证 | `~/.pi/agent/auth.json`（pi-agent 管理，权限 0600）|
+| 项目代码 | monorepo：`workbench/server/`（Hono + pi-coding-agent SDK）+ `workbench/web/`（Vite + React + shadcn/ui）+ `packages/graph-engine/`（共享图谱引擎）|
+
+## Node 版本
+
+`>=22.19.0`（pi-coding-agent 0.75.x 的硬要求）。
+
+仓库根用 `.mise.toml` / `.nvmrc` 锁定。