131 lines
13 KiB
Markdown
131 lines
13 KiB
Markdown
# 个人智能体使用指南
|
||
|
||
安装后从这里开始。它帮助当前 AI 按工程规则完成需求、修复、验证和交付；不是安装后自动工作的后台程序。以下对话示例供你按需发送，阅读本说明不会启动任务或授予示例中的权限。
|
||
|
||
## 第一次使用
|
||
|
||
在 Codex 或 Cursor 中打开目标工程，用新会话发送：
|
||
|
||
```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 和账号连接需要另外配置，本安装器不会自动安装或登录。
|
||
|
||
## 日常开发怎么提需求
|
||
|
||
| 场景 | 可以直接发送的示例 |
|
||
| --- | --- |
|
||
| 新工程建设 | “按个人智能体流程建设项目。目标是……，前端……，后端……，部署约束……。先确认需求、技术栈和目录结构。” |
|
||
| 已有工单 | “请处理当前仓库工单 #123，修改 Web 和移动端。读取正文、全部评论并查看图片后实施。” |
|
||
| 没有工单 | “修复 Web 登录后跳转错误：操作步骤……，当前结果……，期望结果……。先在当前仓库创建工单再修复。” |
|
||
| 新界面或弹窗 | “新增订单筛选弹窗，请先结合现有界面风格在 Figma 制作原型，展示后再按工程确认规则实施。” |
|
||
| 仅讨论方案 | “先分析这项需求，暂不创建工单或修改代码。” |
|
||
|
||
尽量给出修改端、复现步骤、期望结果和截图；没有明确修改端时，Agent 会确认是 Web、移动端还是所有相关端。工单的完整评论及图片会纳入理解；无法访问的图片会报告缺口，不按链接文字猜测。
|
||
|
||
新页面、新弹窗和视觉改版默认先做 Figma 原型。确实无需原型时明确说“本次不用生成 Figma 原型”；仍按已有界面规范实现。需要等待你亲自确认时说“这个决定必须等我回复”。
|
||
|
||
任务通常依次经过：读取工单 → 确认范围/原型 → 任务分支与 worktree 实现 → 任务测试与审查 → 合并结果检查及本机集成环境冒烟 → 按授权更新远端主分支 → 恢复核对本机环境并关单。worktree 是独立工作目录，里面有对应任务分支；它不是集成主分支，不能只刷新原来的页面就认定正在测试修复版。
|
||
|
||
## 谁来测试，何时合并
|
||
|
||
默认由 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 或旧构建产物。
|
||
|
||
## 批量处理工单
|
||
|
||
先在工程仓库中为准备交给 AI 的工单添加 `ai-ready`。队列只处理未关闭、无指派人且没有 `ai-blocked` / `ai-in-progress` 的工单，PR 不参与。可用 `p0` 至 `p3` 表示优先级，p0 最高；同级先处理较早创建的工单。
|
||
|
||
| 你要做什么 | 对 Agent 说 |
|
||
| --- | --- |
|
||
| 查看当前进度 | “查看本工程工单队列状态，先不要启动。” |
|
||
| 开始逐个处理 | “开始处理本工程的 ai-ready 工单，按个人智能体队列流程逐个开发。” |
|
||
| 停止 | “结束处理工单。保留当前代码和进度，不再继续实现、合并或领取下一单。” |
|
||
| 恢复 | “继续处理工单，先核对并续接上次未完成的任务。” |
|
||
| 重试阻塞任务 | “工单 #123 的阻碍已解除，请核对状态后重试。” |
|
||
|
||
开始前需核对仓库、集成分支、Git 推送和工单读取/回写权限。队列会创建专用远端控制分支以防重复执行，可能触发工程已有的分支 CI。开始队列不等于新增部署、Tag 或服务启停授权。
|
||
|
||
队列在当前会话运行，处理完会停止；关闭应用、会话中断后不会自行继续。停止会保留当前任务，已发出的请求可能无法即时取消。新会话须明确续接；另一电脑遇到仓库占用时先核对原执行者，不能删除锁强行抢单。具体操作与异常恢复以安装目录 `references/issue-queue.md` 为准。
|
||
|
||
## 打包、账号和更新
|
||
|
||
**打包按项目选择。** Drone + Tag 只是可选模式，也可以使用其他 CI、人工打包或暂不打包。已有方案沿用，没确定时由 Agent 帮你确认；正常合并不会自动授权部署。你可以说：“本工程使用人工 Docker 打包，不配置 Drone。”
|
||
|
||
**两类凭据分开。** 代码运行所需账号继续放在对应 `.env`、配置或环境注入中。供 Agent 操作服务器、Git/设计平台的账号可放在工程 `.local/secrets/access.json`，创建和使用前核对 Git/Docker/交付排除与权限；不要提交真实值。已有登录会话或外部凭据来源可继续使用，操作凭据不会随 Git 同步。
|
||
|
||
**更新按工程选择。** 对 Agent 说：“检查个人智能体更新，给我版本和变更说明，先不要安装。”选择更新后让它预览并应用；也可选择稍后或跳过。每个工程独立更新，进行中的任务不应悄悄换规则，更新完成后新开会话使用。
|
||
|
||
旧协议 1 升级到 2，需要用最新完整源码的安装器执行一次 `init` 预览及 `init --apply`，保留已有配置；之后协议兼容的更新可使用工程内 updater。单独更新个人源码仓库不会自动更新所有工程。升级生成的受管文件审阅并提交到工程 Git 后，其他电脑拉取该工程可取得相同规则；本地账号与队列状态不随之同步。
|
||
|
||
## 常见问题
|
||
|
||
| 情况 | 处理方式 |
|
||
| --- | --- |
|
||
| 不能读取工单或图片 | 让 Agent 报告具体权限/连接缺口，使用已授权连接或补充可访问材料；不要把缺图当已理解。 |
|
||
| 有工单却没被领取 | 核对仓库、标签、指派人及阻塞记录；曾完成后重新打开的工单需要明确重试。 |
|
||
| 显示仓库队列已被占用 | 先确认另一会话/电脑是否还在处理，再按队列恢复规则操作，保留原工作。 |
|
||
| 升级提示文件冲突 | 保留现场，让 Agent 比较本地修改；不要删除 lock 或强制覆盖。工程个性规则放在非受管区或工程配置。 |
|
||
| 安装/升级中断 | 让 Agent 先预览恢复；协议 1→2 中断用完整协议 2 源码 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`：仅记录工程事先授予的动作范围，true 必须有用户授权依据；不覆盖宿主限制和当前会话指令。未获授权的初始值为 false。用户明确采用自动收尾流程后，将 push_task_branch、create_pr、write_issue、merge 记录为 true，并在工程规则中保留授权依据；push_tag、deploy 仍分别授权。当前明确指令优先于旧配置，已有授权不重复询问。
|
||
- `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 只检查本地存在与候选入口摘要，不证明完整依赖、宿主调用或远端连接可用。
|