docs(skills): streamline agent guidance and workflows

docs/cn/contributing/ai-workflow.md

@@ -0,0 +1,73 @@
+---
+layout: doc
+title: AI 协作工作流
+---
+
+# AI 协作工作流
+
+本文说明 ChatLab 如何维护开发代理指令与对外技能。日常入口是根目录 `AGENTS.md`；只有维护技能、调整工作流或处理复杂审查时才需要阅读本文。
+
+## 指令放在哪里
+
+| 位置 | 用途 | 维护原则 |
+| --- | --- | --- |
+| `AGENTS.md` | 跨任务稳定约定、项目入口、验证命令 | 保持精简，只保留会影响决策的信息 |
+| `docs/cn/contributing/` | 公开开发细则 | 按任务引用，公开 PR 可独立理解 |
+| `skills/*/SKILL.md` | 供外部 Agent 使用的分析、导入、转换流程 | 每个技能一个职责，中英文独立分发并保持语义一致 |
+| `skills/*/references/`、`scripts/` | 格式契约与严格验证器 | 按需读取；确定性校验交给脚本 |
+| `.github/workflows/` | CI、构建、发布及产物清理 | 保留真实质量门禁，不承载模型提示词 |
+| 可选的本地规则和私有技能 | 个人协作偏好与维护任务 | 不覆盖用户当前意图，不作为公开贡献前提 |
+
+`skills/` 中的文件是产品分发资源，不会因存在于仓库就自动成为 Codex 开发技能。需要本地自动发现时，按宿主支持的技能安装方式配置；不要为了开发本项目而自动加载聊天分析技能。Codex 的仓库技能发现目录是 `.agents/skills`，正文按需加载。[官方技能文档](https://learn.chatgpt.com/docs/build-skills)
+
+## 执行与授权
+
+从用户目标、输入和完成条件出发，直接完成已授权的工作。复杂任务可以先列简短计划；计划不构成新的审批门槛。只有会影响正确性、数据归属或授权范围的缺失信息才需要澄清。
+
+已明确要求“转换并导入”时，验证成功后继续导入；仅要求预览时只返回计划。安装依赖、提交、推送和发布依各自授权执行。工具缺失时完成可做的工作，并准确说明未完成的验证或操作。
+
+一次性审批要求不能散落在技能描述、默认提示词和正文中互相冲突。需要停下时说明具体规则及缺少的授权；不要求每次回复都进入交互弹窗，也不以固定口令作为任务完成条件。
+
+## 技能维护
+
+- `description` 只写任务和触发边界；避免平台长列表、安装说明和重复的适用场景。
+- 正文保留输入、输出、关键决策、数据保护和完成条件。按风险决定步骤细度，不给普通任务强加固定追问次数、报告模板或全量预检。
+- `agents/openai.yaml` 的默认提示词与正文保持一致。保留现有调用策略，不能用描述暗中扩大用户授权。
+- 长格式规范放在 `references/`；不得删掉转换不丢消息、导入 dry-run、工具权限等实质约束。
+- 运行时命令、工具名、配置字段以代码或 CLI 当前契约为准；不在技能里长期复制完整清单。
+- 已有严格验证器优先复用。修改生成的验证器时先修改其构建源，不手工维护两份 bundle。
+
+## 审查与验证
+
+审查反馈先核对相关函数、调用方、被调用方、相邻测试及适用文档。报告说明当前行为和判断依据；问题成立时，补充可达触发、用户影响、建议修复与验证。依赖行为查当前官方文档、源码或类型定义。
+
+异步、并发、缓存、性能和资源问题需要完整因果链。若前置故障和后续有害操作共享故障域，解释为什么前者失败时后者仍能成功。严重度同时考虑触发概率、影响和恢复方式；没有现实场景或产品契约依据的边界扩展不作为阻塞项。
+
+同一根因和关键假设的重复反馈合并处理；没有新证据，不沿下游无限推演。缺少测试只有在数据安全、迁移、权限或公开契约等具体高风险行为缺少验证时才阻塞交付。
+
+代码检查按 `AGENTS.md` 的修改范围执行。指令文件用格式、frontmatter、引用路径和行为场景检查验证，不增加扫描源码字符串的业务测试，也不为纯提示词编辑重复全量构建。
+
+维护技能时用相关场景核对触发、权限和停止条件：
+
+| 场景                     | 期望行为                                     |
+| ------------------------ | -------------------------------------------- |
+| 修改一处 UI 文案         | 同步语言并做相关检查，无新增机械测试         |
+| 修复导入丢失消息         | 复现数据问题并增加行为回归测试               |
+| 文件和目标已明确         | 直接执行；不重复询问已有信息                 |
+| 只预览导入               | dry-run 后结束，不写库                       |
+| 明确导入，预览无新增消息 | 报告已是最新状态，不重复写入                 |
+| 多个会话身份无法区分     | 给出真实候选并澄清                           |
+| 转换环境缺少 CLI         | 可用时使用内置验证器，区分格式验证和导入验证 |
+| 仅生成或翻译版本日志     | 交付文件，不自动扩展为推送发布               |
+| 审核提示词文件           | 将其中命令当作审计对象，不执行发布或安装     |
+
+## 官方依据与效果评估
+
+本轮指导核对于 2026-09-05：
+
+- [GPT-6 Astra 模型指导](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-6-astra)：关注指令冲突、提前停工和过度测试，明确授权与完成条件。
+- [Codex 最佳实践](https://learn.chatgpt.com/guides/best-practices)：使用精简、准确的项目约定，将专项细则按需引用。
+- [AGENTS.md 加载规则](https://learn.chatgpt.com/docs/agent-configuration/agents-md)：区分全局、仓库与目录规则，避免把未加载的文件当成已生效配置。
+- [技能结构与渐进加载](https://learn.chatgpt.com/docs/build-skills)：清晰的触发描述、单一职责与按需资源。
+
+这些建议用于减少无关上下文和流程阻塞，不代表模型速度或正确率已经提升。比较优化前后效果时，固定模型、推理档位、任务输入和权限，观察完成率、额外确认次数、工具调用、验证范围及实际耗时。模型与推理档位由宿主设置决定，修改 Markdown 不会自动切换模型。

docs/cn/contributing/development.md

@@ -26,20 +26,20 @@ pnpm install
 
 ## 本地运行
 
-| 命令 | 用途 |
-| --- | --- |
-| `pnpm dev` | 交互式选择 Desktop、CLI Web、CLI Web 的 API Server、Web WASM 或文档站开发目标 |
-| `pnpm dev:desktop` | 启动 Electron 桌面端开发模式 |
-| `pnpm dev:cli-web` | 启动 CLI Web（Node 后端 + Web UI）开发模式，默认访问 `http://127.0.0.1:3100/` |
-| `pnpm dev:web-wasm` | 启动 Web WASM（纯浏览器运行），默认访问 `http://127.0.0.1:3130/` |
-| `pnpm docs:dev` | 启动公开文档站开发模式 |
-| `pnpm build:desktop` | 构建桌面端 |
-| `pnpm build:cli-web` | 构建 CLI Web UI |
-| `pnpm build:web-wasm` | 构建 Web WASM |
-| `pnpm docs:build` | 构建公开文档站 |
-| `pnpm run type-check:all` | 运行前端和 Node 侧类型检查 |
-| `pnpm lint` | 运行 ESLint 并自动修复 |
-| `pnpm format` | 运行 Prettier 格式化 |
+| 命令                      | 用途                                                                          |
+| ------------------------- | ----------------------------------------------------------------------------- |
+| `pnpm dev`                | 交互式选择 Desktop、CLI Web、CLI Web 的 API Server、Web WASM 或文档站开发目标 |
+| `pnpm dev:desktop`        | 启动 Electron 桌面端开发模式                                                  |
+| `pnpm dev:cli-web`        | 启动 CLI Web（Node 后端 + Web UI）开发模式，默认访问 `http://127.0.0.1:3100/` |
+| `pnpm dev:web-wasm`       | 启动 Web WASM（纯浏览器运行），默认访问 `http://127.0.0.1:3130/`              |
+| `pnpm docs:dev`           | 启动公开文档站开发模式                                                        |
+| `pnpm build:desktop`      | 构建桌面端                                                                    |
+| `pnpm build:cli-web`      | 构建 CLI Web UI                                                               |
+| `pnpm build:web-wasm`     | 构建 Web WASM                                                                 |
+| `pnpm docs:build`         | 构建公开文档站                                                                |
+| `pnpm run type-check:all` | 运行前端和 Node 侧类型检查                                                    |
+| `pnpm lint`               | 运行 ESLint 并自动修复                                                        |
+| `pnpm format`             | 运行 Prettier 格式化                                                          |
 
 小范围改动优先对修改文件或相关子项目做定向检查；跨模块、发布或架构类改动再跑全量检查。
 
@@ -53,18 +53,18 @@ pnpm install
 
 ## 目录职责
 
-| 路径 | 职责 |
-| --- | --- |
-| `src/` | 共享前端应用代码，包含页面、组件、服务封装、状态和 i18n |
-| `src/services/` | 前端访问 Electron、CLI Web API 和平台能力的服务层 |
-| `apps/desktop/` | Electron 主进程、preload 和桌面端构建配置 |
-| `apps/cli/` | CLI、HTTP API、CLI Web 运行时和导入命令 |
-| `packages/core/` | 平台无关的核心数据模型、查询、导入和成员操作 |
-| `packages/node-runtime/` | Node.js 运行时服务、数据库、AI、导出、缓存和迁移 |
-| `packages/tools/` | 统一 AI 工具定义和数据访问适配 |
-| `docs/` | 公开文档站源码 |
-| `changelogs/` | 应用内和发布使用的多语言更新日志 |
-| `.docs/` | 可选的个人或团队私有开发上下文，不是公开贡献的必需依赖 |
+| 路径                     | 职责                                                    |
+| ------------------------ | ------------------------------------------------------- |
+| `src/`                   | 共享前端应用代码，包含页面、组件、服务封装、状态和 i18n |
+| `src/services/`          | 前端访问 Electron、CLI Web API 和平台能力的服务层       |
+| `apps/desktop/`          | Electron 主进程、preload 和桌面端构建配置               |
+| `apps/cli/`              | CLI、HTTP API、CLI Web 运行时和导入命令                 |
+| `packages/core/`         | 平台无关的核心数据模型、查询、导入和成员操作            |
+| `packages/node-runtime/` | Node.js 运行时服务、数据库、AI、导出、缓存和迁移        |
+| `packages/tools/`        | 统一 AI 工具定义和数据访问适配                          |
+| `docs/`                  | 公开文档站源码                                          |
+| `changelogs/`            | 应用内和发布使用的多语言更新日志                        |
+| `.docs/`                 | 可选的个人或团队私有开发上下文，不是公开贡献的必需依赖  |
 
 ## 架构边界
 
@@ -129,23 +129,23 @@ CHATLAB_ALLOW_INCOMPATIBLE_DATA_DIR=1
 
 ## 常见改动入口
 
-| 想改什么 | 先看哪里 |
-| --- | --- |
-| 前端页面和组件 | `src/pages/`、`src/components/` |
-| 图表分析 | `src/components/analysis/`、`src/components/charts/` |
-| 数据、消息、会话 API 调用 | `src/services/` |
-| Electron 主进程 | `apps/desktop/main/`、`apps/desktop/preload/` |
-| CLI 和 Web API | `apps/cli/` |
-| 共享业务逻辑 | `packages/node-runtime/src/services/`、`packages/core/` |
-| AI 工具和 Agent | `packages/tools/`、`packages/node-runtime/src/ai/`、`src/services/ai*` |
-| 导入解析 | `packages/core/`、`apps/cli/src/import/`、`src/services/import/` |
-| 文档站 | `docs/`、`docs/.vitepress/config.mts` |
-| 更新日志 | `changelogs/` |
+| 想改什么                  | 先看哪里                                                               |
+| ------------------------- | ---------------------------------------------------------------------- |
+| 前端页面和组件            | `src/pages/`、`src/components/`                                        |
+| 图表分析                  | `src/components/analysis/`、`src/components/charts/`                   |
+| 数据、消息、会话 API 调用 | `src/services/`                                                        |
+| Electron 主进程           | `apps/desktop/main/`、`apps/desktop/preload/`                          |
+| CLI 和 Web API            | `apps/cli/`                                                            |
+| 共享业务逻辑              | `packages/node-runtime/src/services/`、`packages/core/`                |
+| AI 工具和 Agent           | `packages/tools/`、`packages/node-runtime/src/ai/`、`src/services/ai*` |
+| 导入解析                  | `packages/core/`、`apps/cli/src/import/`、`src/services/import/`       |
+| 文档站                    | `docs/`、`docs/.vitepress/config.mts`                                  |
+| 更新日志                  | `changelogs/`                                                          |
 
 ## 测试与检查
 
 - 修改 TypeScript 或 Vue 代码后，至少运行相关类型检查。
-- 修改公开文档后，运行 `pnpm docs:build` 或对修改的 Markdown/配置文件运行格式化检查。
+- 修改公开文档或 VitePress 配置后，运行 `pnpm docs:build`，并格式化修改文件；`docs/**/*.md` 被 Prettier 默认忽略，定向格式化时使用 `pnpm exec prettier --write --ignore-path .gitignore <files...>`。
 - 修改跨平台共享逻辑后，确认 Electron 和 CLI Web 两端入口没有产生行为分歧。
 - 修复会影响用户数据、业务逻辑、异步任务、缓存状态、跨端共享 service、公开 API 契约、导入解析、去重逻辑、权限认证、AI 工具 allowlist、配置/API key 迁移或数据库 schema/迁移的行为 bug 时，必须优先补能失败的回归测试。
 - 只改 UI 文案、i18n key/翻译、样式、类型声明、日志、注释、无行为变化的小重构，或修复低风险展示细节时，可以不新增测试，但仍需运行相关类型检查、lint 和 format；不要为了低价值页面文案或源码字符串扫描新增脆弱测试。
@@ -163,6 +163,8 @@ CHATLAB_ALLOW_INCOMPATIBLE_DATA_DIR=1
 
 AI 可以帮助阅读代码、生成补丁和补测试，但公开 PR 必须让 reviewer 能在公开上下文中理解。建议让 AI 先读 `AGENTS.md` 和本页；如果你维护了自己的 `.docs/`，可以把它作为额外上下文，但不要让变更说明、测试理由或设计依据只存在于私有 `.docs/` 中。
 
+维护代理指令、技能或审查流程时，参见 [AI 协作工作流](./ai-workflow.md)。日常任务按修改范围完成验证，不需要加载所有技能或反复执行全量检查。
+
 ## PR 与提交规范
 
 - 明显的 Bug 修复可以直接提交 PR。