# pi-work-agent 功能审查 / Capability Audit

本轮目标：补齐已接入的四个系统日常读写协作流程，并修复共性缺陷；不是无限制开放所有管理 API，也不修改真实企业数据。

## 已发现并修复

| 缺口 | 修复 |
| --- | --- |
| Confluence 仅两个读工具，无页面更新能力 | 页面创建/版本化更新/删除、子页面、评论、标签、身份及 JSON REST |
| Confluence 声称 REST v2，但实际访问 `/rest/api` | 明确为 legacy v1；Cloud v2 通过限定 `/api/v2` 的 REST 提供 |
| GitHub 仅三种读取 | Issue、评论、文件 commit、PR 创建/更新/合并/review、Actions dispatch、JSON REST |
| GitLab 没有 MR/流水线/文件创建 | 增加 MR 查询/创建/更新/带 SHA 合并、显式 ref 流水线、文件创建、JSON REST |
| GitLab 项目过滤依赖全局接口 query | 改为真正的项目级 `/projects/:id/search` 和 `/projects/:id/issues` |
| Confluence/GitHub 默认可能选到其他类型 | 所有系统按类型解析，显式错误类型拒绝 |
| `settings.defaultConnector` 未生效 | 同类型优先配置默认连接，跨类型选择首个成功连接 |
| 超时设置仅部分系统使用 | 四系统继承全局超时，支持单连接覆盖 |
| 默认文件分支假设 main | GitHub 省略 ref，GitLab 使用 HEAD |
| 写队列各系统独立，跨系统确认框可能重叠 | 四系统共享确认/提交队列 |
| 旧工具错误信息当普通成功返回 | 抛出工具异常，pi 正确标记 isError |
| 输出可能过大 | 所有工具使用统一上限，完整结果保存 0600 临时文件 |
| HTTP 204 JSON header 解析失败 | 空响应明确返回 success/status |
| 登录 HTML/redirect 可能当成功或外泄凭据 | 禁止重定向，非 JSON 报错，限定 same-host paths |
| 并发修改覆盖 | Confluence 当前版本+1；GitHub 文件 blob SHA、合并 head SHA；GitLab 合并 head SHA/文件可选 last_commit_id |
| 注册/配置可观测性不足 | `work_list_connections` 安全元数据，类型/只读/默认/超时校验 |
| reload/关闭清理不足 | 初始化清空失效连接，shutdown 关闭并清空注册表 |
| 文档包名与真实 npm 名不一致 | 修正为 `ljdou-pi-work-agent`，同步清单、示例、安装/限制 |

## 当前计数

| 系统 | 工具数 |
| --- | ---: |
| Jira | 26 |
| Confluence | 15 |
| GitLab | 23 |
| GitHub | 22 |
| 跨系统连接发现 | 1 |
| 总计 | 87 |

## 仍有边界（不应宣称“全部实现”）

1. **版本/产品/API 权限差异**：Confluence 专用工具是 legacy v1；Cloud 可经 REST 请求 v2，但不是原生完整 v2 adapter。旧 Server 元数据端点、许可证、Token scope、平台工作流约束仍需真实部署验证。
2. **Multipart / binary**：目前只有 Jira 本地附件上传专用实现（20MiB）。Confluence/GitLab/GitHub 非 JSON 上传、二进制下载、Git LFS 不支持。仓库文件工具面向 UTF-8 内容。
3. **API 命名空间**：Jira JSM/插件专有前缀、GitHub GraphQL、任意 URL/代理访问不会通过 JSON REST 工具放行。
4. **复杂 review/discussion**：代码 diff 评论、MR discussions/approvals、labels/milestones/branch/release/jobs 等多数 JSON 能力可通过受限通用 REST，但没有为每个接口注册专用高层工具。需要查产品接口，并明确影响范围。
5. **事务/重试**：没有跨系统事务/自动回滚/分布式锁；写请求不自动重试。超时/取消后必须先验证结果。不会自动合并版本冲突。
6. **审批模式**：Print/JSON 无交互时禁止写；RPC 客户端必须实现 extension UI 确认协议。不提供模型自证确认或无人值守绕过。
7. **Live verification**：自动测试模拟 HTTP，不代表真实租户 API/权限端到端验收。真实写入需用户按连接/项目/Issue 或文件分支及操作逐次确认。
8. **新增系统**：Slack/Notion/飞书/企业微信尚未接入；本轮只完善已支持的四个系统。
9. **发布/安装**：本轮本地 source/dist 改动不等于 npm 发布。配置模板不覆盖已有私有配置；独立安装包需另更新。setup 保留原有 wrapper 行为，不修改用户凭据。
10. **临时文件**：完整工具输出可能含业务数据；存私有目录/0600 文件，按本地主机策略清理，不默认上传外部。

## 质量验证

- `npm test --workspace=packages/pi-work-agent`：构建并执行模拟 HTTP 测试。
- `npm exec --workspace=packages/pi-work-agent -- tsc --noEmit -p tsconfig.json`：类型检查。
- 专用读写端点/payload、SHA/version/ref、身份/用户确认/取消、readOnly、同类型 default、并行跨系统确认、204/错误/重定向/路径穿越、输出私有文件、入口注册与 lifecycle 回归。