zkxw/docs/agents/README.md

# 个人智能体使用指南

安装后从这里开始。它帮助当前 AI 按工程规则完成需求、修复、验证和交付；不是安装后自动工作的后台程序。以下对话示例供你按需发送，阅读本说明不会启动任务或授予示例中的权限。

## 快速开始

在目标工程中打开新会话，任选一句发送，替换其中的工单链接或需求描述即可。首次接入检查由 Agent 随任务完成，不需要先单独检查、再启动任务。

**开发一张工单：**

```text
按个人智能体流程开发这张工单：<工单链接或编号>。自动检查工程接入，读取正文、全部评论和图片，沿用已有配置与授权，只在缺少必要信息或权限时问我。
```

**直接描述需求或 Bug：**

```text
按个人智能体流程处理：<需求，或复现步骤、当前结果与期望结果>。先检查工程现状，沿用已有配置与授权，按流程建立工单并开发，只确认必要缺口。
```

**更新后续接已有任务：**

```text
按个人智能体流程继续工单 <链接或编号>。先核对原任务进度、占用、分支和 worktree，沿用已有授权，从未完成步骤继续，不重复领取或重做已完成工作。
```

注意：安装或更新只准备规则与工具，不代表账号、测试环境已验证，也不新增推送、PR、合并或关单权限。批量队列及持续监听需要另行明确开启。更新前保存任务进度，成功后在新会话读取新规则；续接仍须核对原执行者和占用，不能自动接管其他会话。

更多场景、授权和排障见工程 `docs/agents/README.md` 下文。以上是可选示例，展示或阅读不会启动任务。

## 可选：只检查接入

暂时没有开发任务，或只想检查安装时，在目标工程的新会话发送（不是开发前必做步骤）：

```text
请按本工程的个人智能体工作。
先读取 AGENTS.md、.agents/skills/personal-dev/SKILL.md 和 docs/agents/project.json，
检查当前接入情况，只向我确认缺失的信息，暂不开发业务或启动工单队列。
```

Agent 会核对工程仓库、集成主分支、应用目录、测试入口、所需账号和授权。已有事实直接沿用，不必重新描述整个项目。配置未知不代表已完成，检查发现缺项时再补充。

如找不到入口，先确认工程中存在 `.agents/skills/personal-dev/SKILL.md` 及其 `scripts/pda.py`。只有单项 Skill 而没有脚本时，需要完整接入；安装方法见个人仓库的[安装说明](https://github.com/longwu1988/pensonal-dev-agent/blob/main/docs/installation.md)。第三方技能、Figma MCP 和账号连接需要另外配置，本安装器不会自动安装或登录。

## 一分钟推荐选择默认启用

新版个人智能体在处理任务时默认使用这条规则，无需额外说“开启”。Agent 遇到需要你决定的事项，会给出推荐答案、理由、影响和超时说明；真实等待 60 秒仍未回复，且当前任务授权与前置条件允许时，按推荐继续并记录决定来源。

选择题的推荐项会放在第一项并明确标记“推荐”。涉及“已放行端口、已登录、已验收”等事实时，推荐的是核实或后续安排，超时不会替你确认这些事实。漏了推荐或超时说明的旧题须补齐重发、重新计时；这不是界面的自动点击功能，宿主阻塞等待或会话结束时不保证自动继续。

你可以说“本题必须等我回复”“本次任务关闭一分钟默认选择”，或“本工程关闭一分钟默认选择”。工程级选择记录在工程自己的 AGENTS.md 非受管区或既有规则中，升级会保留；恢复时说“恢复本工程一分钟默认选择”，待决定的问题重新展示推荐并计时。配置文件无需新增字段。

没有回复不代表验收通过、凭据已取得或新增操作已获授权。必须回答/批准的事项继续等待，只推进允许的独立工作；工单自动监听不会因此开启，个人智能体更新也不会自动安装。这是当前会话的流程规则，不是后台计时器；会话中断时不保证到点继续。升级后新任务读取新规则，旧问题不追溯计时。细则见安装目录 `references/planning.md`。

## 确认问题会有语音提醒

Agent 发出需要你答复的问题后，默认在本机播放一次“有问题待确认，请及时处理”。语音已预先生成并随包安装，后续只播放本地文件；一批多个问题提醒一次，等待期间不循环播放。

“必须等我回复”的问题也会提醒，但仍保持等待。可以说“本次任务静音”或“本工程关闭语音提醒”，恢复时说“恢复语音提醒”；声音开关和一分钟默认选择互相独立，升级保留工程自己的选择。播放失败不影响文字提问，也不会延长或跳过 60 秒计时。

完整安装提供 `notify-question` 命令，由 Agent 在提问后调用，不是宿主自动弹窗钩子。当前支持用户 macOS 本机；其他系统或远程执行缺少本地播放条件时回退文字提醒，不代表你已听到。安装、更新、普通进度和结束答复不播放。细则见安装目录 `references/question-notification.md`。

## 日常开发怎么提需求

| 场景 | 可以直接发送的示例 |
| --- | --- |
| 新工程建设 | “按个人智能体流程建设项目。目标是……，前端……，后端……，部署约束……。先确认需求、技术栈和目录结构。” |
| 已有工单 | “请处理当前仓库工单 #123，修改 Web 和移动端。读取正文、全部评论并查看图片后实施。” |
| 没有工单 | “修复 Web 登录后跳转错误：操作步骤……，当前结果……，期望结果……。先在当前仓库创建工单再修复。” |
| 新界面或弹窗 | “新增订单筛选弹窗，请先结合现有界面风格在 Figma 制作原型，展示后再按工程确认规则实施。” |
| 仅讨论方案 | “先分析这项需求，暂不创建工单或修改代码。” |

尽量给出修改端、复现步骤、期望结果和截图；没有明确修改端时，Agent 会确认是 Web、移动端还是所有相关端。工单的完整评论及图片会纳入理解；无法访问的图片会报告缺口，不按链接文字猜测。

新页面、新弹窗和视觉改版默认先做 Figma 原型。确实无需原型时明确说“本次不用生成 Figma 原型”；仍按已有界面规范实现。需要等待你亲自确认时说“这个决定必须等我回复”。

任务通常依次经过：原子领取并读取工单 → 确认范围/原型 → 任务分支与 worktree 实现 → 推送任务分支并创建/复用 PR → 测试与审查 → 合并候选检查及本机集成环境冒烟 → 按授权合并 PR → 恢复核对本机环境并关单。worktree 是独立工作目录，里面有对应任务分支；它不是集成主分支，不能只刷新原来的页面就认定正在测试修复版。

## 仅允许本会话处理一张工单

可以明确说：“仅允许当前会话处理 #6 的占用与状态标签；禁止业务代码 push、创建 PR、合并、发表评论和关单。不要修改工程长期授权。” Agent 会把允许与拒绝项写入本地 `.local/agent/permissions/<owner>.json`，绑定仓库、集成分支、会话和工单，再用 `queue-start --issue 6` 启动限定单。它不会因此领取其他工单、重试其他编号或启动持续监听。

占用和标签分别使用 `manage_claims`、`update_issue_labels`，不需要开放 `push_task_branch`、`write_issue`。工单内容/评论用 `write_issue`，关闭用独立的 `close_issue`。你当前的禁止项高于旧工程授权；撤销也不会恢复旧的 true。另一会话或转交后的执行者需有自己的授权。已有明确授权不重复询问，只在确实缺少具体动作的授权时说明范围。

需要检查可让 Agent 运行 `permissions-status --owner CURRENT_OWNER`；grant/revoke 默认预览，加 `--apply` 只改本地记录。业务平台写入前还会在队列守卫之外检查相应能力，检查本身不执行 push、评论或关单，也不是平台账号鉴权。完整命令与权威规则见安装目录 `references/permissions.md`。

## 默认通过 PR 交付

通常一个工单对应一个任务分支/worktree 和一个 PR，目标是本工程指定的集成分支（不固定为 main）。已有自动收尾授权时，Agent 在验证、审查和仓库必需检查通过后自动合并；不需要你逐个点击。PR 权限不足或必需检查未通过时会保留阻碍，不自动改为直接推送。

工程已明确选择直接合并则沿用；希望切换时可说：“本工程使用 PR 合并”，或“本工程明确采用本地合并后直接推送集成分支，保留相同测试与关单流程”。Agent 将选择记录在工程自己的 AGENTS.md 非受管区或已有工程规则中；当前 project.json 无合并方式字段，不要自行新增。升级不覆盖这些规则，也不修改仓库保护或启用 CI。

PR 合并后仍需同步本机、核对环境、回写并关闭工单，再检查清理 worktree。使用普通工单链接关联，避免自动关闭关键字使工单提前关闭。具体规则见安装目录 `references/pull-requests.md`；PR 操作由 Agent 使用平台工具完成，pda.py 不提供 PR 操作命令。

## 谁来测试，何时合并

默认由 Agent 执行适用的测试、构建和界面验证。若工程已授权常规自动收尾，通过后会合入指定集成分支、推送并关闭工单；仅安装智能体不会授予这些权限。你希望采用此方式时，可以明确发送：

```text
本工程常规需求和修复默认由 Agent 测试。
长期授权本工程常规任务维护工单占用及同步流程标签。
测试与审查通过后，授权推送任务分支、创建 PR、合入已确认的集成分支，
同步本地与远端并回写、关闭对应工单。
打 Tag、部署及服务启停仍按工程单独授权。
```

你自己测试时发送：

```text
这次我来测试。完成实现和代码审查后，给我任务分支、worktree 路径、提交号、
前后端运行入口和验证步骤。必须等我明确反馈，不要自动测试、构建或合并。
```

任务版本验证通过后回复“该提交测试通过，请继续集成环境验证与收尾”；失败则发复现步骤和截图。服务实际运行的目录、端口和提交须对应待测版本，服务启停仍遵守工程规则。

“一分钟推荐选择”默认启用且未被关闭时，没有回复可能按已展示的推荐转为 Agent 实际测试，但沉默不会被记为用户验收通过；上面的“必须等我”会要求本次保持等待。提问、原型及测试细则分别见安装目录 `references/planning.md`、`ui-design.md`、`testing.md`。

## 修复后，本机环境怎样切回主分支

任务版本先在独立分支/worktree 中验证。通过后结合最新主分支准备合并结果，把本机环境切到集成版本做启动、前后端连通和关键功能冒烟检查；通过后才更新远端主分支。默认 PR 模式先用本地等价集成候选验证，再合并远端并安全同步本地。

失败时保留现场，回原任务分支修复、重新验证和集成，不在主分支直接补丁式修改，也不关闭工单。相同代码不重复全部测试，但目录、容器、配置、数据库或产物变化仍要验证；纯文档等无运行影响时可记录不适用。

你选择自己测试时，任务验证和集成环境冒烟都由你完成。禁止 Agent 启停服务的工程，仍由你操作；未完成必要环境验证前暂不更新远端主分支、关单。worktree 不自动隔离端口或数据库，也不会自动重启服务。可以说：“请提供任务版本和切回主分支后的两阶段验证入口，服务由我启停。”

完整步骤见安装目录 `references/local-validation.md`。合并后还要核对本机真正运行的是集成版本，避免仍在访问旧 worktree 或旧构建产物。

普通工单和队列共用收尾检查。你说“验证通过，请提交并 push”时，智能体应续接原工单，在已有授权且必要验证完成后回写、关闭并重新读取确认。最终回复会列出工单、PR 状态或直接合并依据、提交、验收依据及关闭状态；只推送成功不代表工单完成。要暂缓可明确说“只推送，先不要关闭工单”。

本地收尾进度保存在 Git 忽略的 `.local/agent/delivery/`，由 Agent 使用 `delivery-status`、`delivery-record`、`delivery-check`；普通工单与队列取得占用后都使用 `queue-finish`，无需你手动运行一串命令。中断后先核对已完成动作，不重复发表评论。详见安装目录 `references/completion.md`。这些命令不自动测试、关单或后台续跑。

## Worktree 放在哪里

默认优先由宿主管理，使用返回的实际路径；Git 兜底时在工程根目录的 `.local/agent/worktrees/` 下，采用 `issue-编号-简述-唯一短ID`。分支默认 `codex/issue-编号-简述-唯一短ID`，工程明确约定优先。续接核对并复用原任务，旧目录不自动改名；当前分支和提交以 Git 为准。

两个工程的目录通常分离，但端口、Docker 容器和测试数据仍需独立安排。个人智能体的资源锁按仓库隔离，目前没有跨工程全局环境锁。你可以说：“同时处理这两个工程，请先核对各自 worktree 归属、端口、Docker 项目名和测试数据隔离，冲突时保留其他工程环境。” 细则见安装目录 `references/worktree-layout.md` 和 `references/local-validation.md`。

## 批量处理工单

先在工程仓库中为准备交给 AI 的工单添加 `ai-ready`。队列只处理未关闭、无指派人且没有其他流程状态标签 的工单，PR 不参与。可用 `p0` 至 `p3` 表示优先级，p0 最高；同级先处理较早创建的工单。

| 你要做什么 | 对 Agent 说 |
| --- | --- |
| 查看当前进度 | “查看本工程工单队列状态，先不要启动。” |
| 开始逐个处理 | “开始处理本工程的 ai-ready 工单，按个人智能体队列流程逐个开发。” |
| 停止 | “结束处理工单。保留当前代码和进度，不再继续实现、合并或领取下一单。” |
| 恢复 | “继续处理工单，先核对并续接上次未完成的任务。” |
| 重试阻塞任务 | “工单 #123 的阻碍已解除，请核对状态后重试。” |

开始前需核对仓库、集成分支、工程级占用/标签权限及对应 Git/API 凭据；仅有单工单授权时使用限定单流程。业务代码推送、评论、PR、合并与关单分别检查权限。队列会创建专用远端控制分支及每单占用记录以防重复执行，可能触发工程已有的分支 CI。开始队列不等于新增部署、Tag 或服务启停授权。

默认一次性队列在当前会话运行，处理完会停止；关闭应用、会话中断后不会自行继续。停止会保留当前任务，已发出的请求可能无法即时取消。新会话须明确续接；另一电脑遇到该工单占用时先核对原执行者，不能删除锁强行抢单。具体操作与异常恢复以安装目录 `references/issue-queue.md` 为准。

### 多会话与状态

每个会话一次处理一张工单。A 正处理 #1 时，B 跳过 #1，领取下一张可处理工单；共享环境和最终合并依次进行。标签用于查看进度，远端原子占用才是能否继续的依据；完成和阻塞记录不会因重启而被自动重新领取。

| 标签 | 含义 |
| --- | --- |
| `ai-ready` | 等待领取 |
| `ai-in-progress` | 已领取，分析或实现中 |
| `ai-testing` | 测试或审查中 |
| `ai-waiting-user` | 等待用户验收 |
| `ai-ready-to-merge` | 验收与集成验证已通过，等待合并 |
| `ai-merging` | 已获集成锁，合并及交付收尾中 |
| `ai-done` | 推送、环境核对、回写和关闭均核验完成 |
| `ai-blocked` | 记录了阻碍，不能自动重领 |

可说“只停止本会话，其他会话继续”，或“停止本机本工程所有工单会话”。全停令牌不跨电脑同步；其他电脑须分别停止。转交未完成工单需要明确指令、核对原会话已停止及资源已释放，保留原分支/worktree 后转交。不能仅删标签、等待超时或删除占用记录抢单。规则和命令见安装目录 `references/issue-claims.md`。

### 以后新增工单也自动处理

持续监听须有工程级 `manage_claims`、`update_issue_labels`，单工单授权不能代替；具备权限仍需明确开启。在支持原生同会话调度的 Codex 桌面工程中发送：

```text
开启本工程的持续工单处理，每 5 分钟检查 ai-ready 工单。
当前以及以后新增、符合队列条件的工单都逐个处理，直到我说停止。
沿用工程已有授权、测试责任和合并关单流程；无新进展时不提醒。
请配置并验证真实定时任务，报告计划 ID、首次检查结果和停止方式。
```

随时说“停止持续监听并结束工单处理，保留当前进度”，或“查看持续监听与队列状态，不要启动”。空队列只结束当前轮，后续由定时任务再检查；等待用户验收不自动通过。仅安装或升级不会开启它。电脑需开机且宿主运行，实际频率受宿主支持限制；Cursor 持续调度尚未验证，缺少可用工具时会明确报告未开启。规则和恢复见安装目录 `references/issue-watch.md`。

## Worktree 自动收尾与遗留清理

采用本流程后，每单验收、合并推送并关单核验完成，再检查和回收本任务 worktree，然后领取下一单。本地任务分支默认保留至少 7 天，远端分支默认保留；到期也须重新核对合并与占用条件。等待你测试、失败、阻塞、主动停止、有未保存文件或仍被服务使用的目录都会保留并说明原因。

主工程 `.local/agent/worktree-registry/` 保存归属、提交、清理结果与恢复依据，不提交 Git。默认在启动任务/队列和每单收尾时巡检，持续模式最多每天只读检查一次；超过 5 个保留目录或保留超过 7 天时提醒，不按数量或时间强删，也不另外创建后台清理任务。

可以直接说：

- “查看本工程 worktree 清理情况，列出可清理项和保留原因，先不要删除。”
- “清理本工程中已完成且满足个人智能体检查条件的历史 worktree，保留未完成任务和所有唯一配置。”
- “工单 #123 的 worktree 暂时保留，后续我还要查看。”

规则由安装目录 `references/worktree-lifecycle.md` 统一维护，Agent 实际调用 Git/宿主工具；脚本不会替你自动删除。升级不立即批量清理历史目录；旧运行时缺少 queue-cleanup-guard 时保留队列清理项，更新后再按授权执行。

## 打包、账号和更新

**打包按项目选择。** Drone + Tag 只是可选模式，也可以使用其他 CI、人工打包或暂不打包。已有方案沿用，没确定时由 Agent 帮你确认；正常合并不会自动授权部署。你可以说：“本工程使用人工 Docker 打包，不配置 Drone。”

**两类凭据分开。** 代码运行所需账号继续放在对应 `.env`、配置或环境注入中。供 Agent 操作服务器、Git/设计平台的账号可放在工程 `.local/secrets/access.json`，创建和使用前核对 Git/Docker/交付排除与权限；不要提交真实值。已有登录会话或外部凭据来源可继续使用，操作凭据不会随 Git 同步。

**更新按工程选择。** 对 Agent 说：“检查个人智能体更新，给我版本和变更说明，先不要安装。”选择更新后让它预览并应用；也可选择稍后或跳过。每个工程独立更新，进行中的任务不应悄悄换规则，更新完成后新开会话使用。

本版权限拆分采用协议 6，保留语音提醒。旧协议 1/2/3/4/5 需要用完整协议 6 源码的安装器执行一次 `init` 预览及 `init --apply`，保留已有配置与队列进度；新权限缺省只在内存补 false，不改原 project.json，也不从旧 push/write 权限推导。已有任务先停止旧执行者与调度、保存进度，升级后按既有用户依据记录所需控制授权，再明确续接。之后协议兼容的更新可使用工程内 updater。单独更新个人源码仓库不会自动更新所有工程。升级生成的受管文件审阅并提交到工程 Git 后，其他电脑拉取该工程可取得相同规则；本地账号与队列状态不随之同步。

## 常见问题

| 情况 | 处理方式 |
| --- | --- |
| 不能读取工单或图片 | 让 Agent 报告具体权限/连接缺口，使用已授权连接或补充可访问材料；不要把缺图当已理解。 |
| 有工单却没被领取 | 核对仓库、标签、指派人及阻塞记录；曾完成后重新打开的工单需要明确重试。 |
| 显示工单或旧队列已被占用 | 先确认另一会话/电脑是否还在处理，再按队列恢复规则操作，保留原工作。 |
| 升级提示文件冲突 | 保留现场，让 Agent 比较本地修改；不要删除 lock 或强制覆盖。工程个性规则放在非受管区或工程配置。 |
| 安装/升级中断 | 让 Agent 先预览恢复；协议 1/2/3/4/5→6 中断用完整协议 6 源码 recover。最近一次备份不等于任意历史版本回退。 |
| 有脚本却不自动开发 | 脚本只管理状态与拉取，实际开发和读图由当前 AI 执行；不是定时任务。 |
| 想每天夜间总结 | 当前没有自动夜间调度；可要求一次手动复盘，不能把安装成功当作后台已启用。 |

## 可选的命令检查

通常直接让 Agent 操作即可。需要自己检查时，以下命令分别在**工程根目录**执行；不会启动工单开发，版本检查会写入本地缓存：

```sh
python3 .agents/skills/personal-dev/scripts/pda.py queue-status --project .
python3 .agents/skills/personal-dev/scripts/pda.py check-update --project .
```

`doctor` 需从完整个人仓库源码的 `scripts/pda.py` 调用，不是工程内更新脚本支持的命令。当前运行时要求 Python 3.9+，macOS 已验证，Linux 尚待实测，Windows 暂不支持。真实仓库连续任务、私有附件及 Codex/Cursor 会话行为仍需工程试点；文件检查通过不代表这些连接和行为已验收。

## 工程配置说明

`project.json` 是工程自行维护的输入；安装器升级保留它。路径以工程根目录为基准，未知值用 null 或空列表，不能把未知写成验证通过。

- `project`：项目名称、工程维护的阶段标签、集成分支、工单仓库；初始化用 discovery，可随进度改为 existing、test-deployed 等非空单行标签。阶段仅为描述，不授予部署或其他操作权限；分支不会默认取当前任务分支。
- `apps`：每项提供 name、path、rules 与 validation。validation 是命令/环境说明列表，安装器不会执行。兼容已有工程的 name/directory/test（可选 build）简写，只在内存中映射为标准结构，不重写原文件；简写命令的环境标为 unverified，不能据此认定已经通过验证。
- `decisions`：已确认技术栈与架构决策的文档路径；新工程在开发前确认，既有工程先沿用。
- `worktree`：优先原生机制，fallback 为工程约定的隔离目录；数据库与端口另行隔离。
- `figma`：具体文件/节点引用与状态；配置存在不代表授权或连接成功。
- `delivery`：按工程选择打包/CI 方案；provider、trigger 默认 null（待选择），Drone 仅可选。provider 可为实际 CI 名称、manual（人工）或 none（当前无需打包），trigger 记录实际触发方式或 null（不适用）。status 可为 unverified、user-confirmed 或 not-applicable，evidence 记录决定依据。完整流程见工程内 `.agents/skills/personal-dev/references/delivery.md` 的“打包与 CI 选型”。升级保留已有配置，不将旧模板默认值当作用户确认。
- `permissions`：仅记录用户明确授予的工程长期动作，默认均为 false；新增 manage_claims、update_issue_labels、close_issue，不从旧字段推导授权。一次性指令只记录本会话/工单权限，不改本配置；当前 deny/撤销高于旧工程 true。已有明确依据无需重新询问，权限定义、命令及迁移以安装目录 `references/permissions.md` 为唯一来源。
- `environment`：记录测试环境条件；`secrets` 仅表示 Agent 操作凭据来源，默认指向当前工程的 `.local/secrets/access.json`，不是应用运行密钥的统一路径。应用继续使用各自 `.env`、配置或环境注入；禁止在 project.json 填写真实值。保存、忽略规则、权限及 worktree 使用见工程内 `.agents/skills/personal-dev/references/credentials.md`；已有明确外部来源仍保留。
- `knowledge`：审核后知识与本地报告位置。本版未提供自动调度，schedule_enabled 必须为 false。

各端专用规范继续保留在原位置。任务从工程根目录的 `.agents/skills/personal-dev/SKILL.md` 进入，按需读取其 references。复用上游前核对 `personal-dev.dependencies.json` 中来源；doctor 只检查本地存在与候选入口摘要，不证明完整依赖、宿主调用或远端连接可用。