ljdou-pi-work-agent

Pi 企业协作扩展，连接 Jira / Confluence / GitLab / GitHub，支持常用查询、更新和开发协作流程。

English · 功能审查与剩余限制

安装与配置

npm install ljdou-pi-work-agent

安装脚本在首次安装时生成 ~/.pi/config/work-agent.yaml，并注册全局扩展 wrapper。也可使用 pi 包管理方式：pi install /absolute/path/to/package 或 pi install npm:ljdou-pi-work-agent。凭据只放在私有配置中，不提交 Git。

用 PI_WORK_AGENT_CONFIG 指定其他 YAML/JSON 配置。当前公共配置加载器只支持简化 YAML：不要写行内注释或行内数组，注释放单独一行，数组使用多行列表；也可使用 JSON。

datasources:
  jira-prod:
    type: jira
    url: https://company.atlassian.net
    username: user@example.com
    token: replace-with-token
    # Cloud 使用 3，Server/DC 使用 2（默认）
    apiVersion: "3"
    readOnly: false
    # Cloud 自定义富文本字段，先查询真实 ID
    # richTextFields:
    #   - customfield_12345
  confluence-prod:
    type: confluence
    url: https://company.atlassian.net/wiki
    username: user@example.com
    token: replace-with-token
    readOnly: false
  gitlab-prod:
    type: gitlab
    url: https://gitlab.company.com
    token: replace-with-token
    readOnly: false
  github-prod:
    type: github
    token: replace-with-token
    readOnly: false
    # GHES 可配置 url: https://github.company.com/api/v3
settings:
  defaultConnector: jira-prod
  queryTimeout: 30000

• defaultConnector 仅用于相同系统类型工具；其他系统选择其首个成功连接的连接器。显式 connector 优先；类型不符会拒绝，不会误选其他系统。
• work_list_connections 展示可用连接、类型、URL、只读状态和配置默认项，不返回密码/Token。
• Basic/Bearer 认证：Jira/Confluence 支持 authType: bearer；默认 Basic。GitLab/GitHub 使用 Bearer。
• 全部连接器使用全局 settings.queryTimeout，单连接配置可覆盖。

当前功能

共 87 个工具：Jira 26、Confluence 15、GitLab 23、GitHub 22、连接发现 1。某系统未连接成功时，其工具仍注册，但执行会报告明确连接错误。

Jira：26 个工具

分类	工具
查询	jira_search_issue、jira_get_issue、jira_get_current_user
元数据	jira_get_fields、jira_get_edit_metadata、jira_get_create_metadata、jira_get_transitions、jira_get_link_types
Issue 写入	jira_create_issue、jira_update_issue、jira_delete_issue、jira_transition_issue、jira_assign_issue
评论	jira_get_comments、jira_add_comment、jira_update_comment、jira_delete_comment
工时	jira_get_worklogs、jira_add_worklog、jira_update_worklog、jira_delete_worklog
关联/附件	jira_link_issues、jira_delete_issue_link、jira_upload_attachment、jira_delete_attachment
通用 API	jira_rest_request：Core `/rest/api/2

• 查询开发方案/自测场景真实 customfield ID 后再写入，不能猜字段 ID；先读 Issue 和编辑元数据。
• fields.description 替换原内容，不是追加；追加前先读取合并。fields/update 至少一个非空，同字段不能同时放在两者中。
• v2 保留文本/wiki；v3 将 description/environment、评论、工时备注纯文本转 ADF 段落。显式 ADF 原样传递；自定义富文本需配置 richTextFields 或显式传 ADF。自动转换不会解析 Markdown/wiki 格式。
• Cloud 搜索使用 /search/jql 与 nextPageToken；Server 使用 startAt。创建元数据使用现代分页接口，旧 Server 可用通用 REST 请求旧版接口。
• 状态更新需流转 ID，不直接修改 status；工时保留剩余估时可传 query: {"adjustEstimate":"leave"}。
• deleteSubtasks: true 删除全部子任务。附件最多 20MiB，确认路径/大小/SHA-256，上传同一份已确认字节快照。

Confluence：15 个工具

分类	工具
查询	confluence_search、confluence_get_page、confluence_get_current_user、confluence_get_page_children、confluence_get_comments、confluence_get_labels
页面	confluence_create_page、confluence_update_page、confluence_delete_page
评论	confluence_add_comment、confluence_update_comment、confluence_delete_comment
标签	confluence_add_label、confluence_remove_label
通用 API	confluence_rest_request：legacy /rest/api、Cloud /api/v2

专用工具实际使用 legacy REST v1，不是 v2；能否使用 legacy API 受部署版本影响。Cloud URL 含 /wiki；Server/DC 使用实际 context path。

页面/评论内容为 storage XHTML，不是 Markdown。更新页面需传完整 title、body 和读取到的当前 version，提交 version+1。确认后不再隐藏读取/合并内容；版本冲突直接报告，不自动重试。删除/移入回收站及对子页面影响依部署规则而定，不自动永久清理或恢复。

GitLab：23 个工具

分类	工具
查询	gitlab_search_code、gitlab_get_file、gitlab_search_issue、gitlab_get_issue、gitlab_get_issue_notes、gitlab_get_current_user
Issue	gitlab_create_issue、gitlab_update_issue、gitlab_delete_issue、gitlab_close_issue
评论	gitlab_add_issue_note、gitlab_update_issue_note、gitlab_delete_issue_note
仓库文件	gitlab_create_file、gitlab_update_file、gitlab_delete_file
MR	gitlab_list_merge_requests、gitlab_get_merge_request、gitlab_create_merge_request、gitlab_update_merge_request、gitlab_merge_merge_request
流水线	gitlab_create_pipeline
通用 API	gitlab_rest_request：/api/v4

• Issue/MR 使用项目内 IID，不是全局 ID。projectId 支持数字、原始 group/project 或单次 URL 编码路径。
• 描述是 Markdown，更新会替换；重新打开 Issue 可传 fields.state_event: "reopen"。
• 搜索支持分页和真正的项目级接口。文件读取默认 HEAD（默认分支），不假设 main。
• 文件变更会创建 commit，必须明确分支和完整内容；建议 options.last_commit_id 防止并发覆盖。options 不会覆盖显式分支/内容/commit message。
• MR 合并必须传预期 head SHA，先检查 review/流水线；创建流水线可能部署。Token 写权限、项目角色和保护分支规则仍由 GitLab 强制执行。

GitHub：22 个工具

分类	工具
查询	github_search_code、github_get_file、github_search_issue、github_get_current_user、github_get_issue、github_get_comments
Issue	github_create_issue、github_update_issue（含关闭/重开）
评论	github_add_comment、github_update_comment、github_delete_comment
仓库文件	github_create_file、github_update_file、github_delete_file
PR	github_list_pull_requests、github_get_pull_request、github_create_pull_request、github_update_pull_request、github_merge_pull_request、github_review_pull_request
Actions	github_dispatch_workflow
通用 API	github_rest_request：允许当前 host 的 /repos、/user、/users、/orgs、/search、/notifications、/rate_limit 路径

文件读取省略 ref 使用真实默认分支；完整 UTF-8 文件写入会自动 base64 编码并创建 commit，更新/删除需当前 blob SHA。合并需预期 PR head SHA，API merged: false 会报告失败，不误报成功。Review 绑定指定 commit SHA；Actions 需明确 workflow/ref。

不虚构 GitHub Issue 删除 REST 接口：关闭使用 github_update_issue。普通会话评论不是代码 diff review comment，后者可使用通用 REST。

开发方案/自测场景更新流程

1. work_list_connections 确认连接。
2. 读取 Issue；Jira 额外查询字段 ID/编辑元数据。
3. 在本地将原描述与开发方案/自测场景合并。
4. 调用更新工具，用户核对目标与参数后确认。
5. 再读取核验。

GitLab 示例：

{
  "connector": "gitlab-prod",
  "projectId": "group/project",
  "issueIid": "123",
  "fields": {
    "description": "原需求内容\n\n开发方案：……\n自测场景：……"
  }
}

Confluence 页面更新示例（先读到当前 version=4）：

{
  "connector": "confluence-prod",
  "pageId": "12345",
  "title": "开发方案",
  "body": "<h2>方案</h2><p>内容……</p><h2>自测</h2><p>内容……</p>",
  "version": 4
}

统一安全策略

• 每次外部写入必须由 TUI/RPC 用户确认连接 URL、身份、操作、资源和参数。Print/JSON 拒绝写入，模型不能用 confirmed 标记跳过。
• 四个系统共用写队列，串行确认和提交，避免跨系统弹窗重叠；不是针对其他客户端的分布式锁。
• readOnly: true 在连接器层禁止所有写入（含通用 REST）。平台权限仍需满足。
• 通用 REST 使用原始 JSON，不自动转换富文本；所有非 GET 都需确认（包含 POST search）。批量/管理操作必须先明确实际影响范围。
• URL 不含凭据/query/fragment；拒绝重定向、路径穿越和嵌套编码。支持取消/超时，不自动重试写入；结果未知先查询核验。
• 删除/合并可能不可恢复，commit/CI 可能触发通知和部署；不保证跨系统事务/回滚。敏感文件提交/上传需要明确用户意图。
• 返回限制 48KB / 2000 行，完整 JSON 保存为私有临时文件；建议筛字段、分页，临时文件按本地生命周期清理。
• 覆盖常用工作流与 JSON REST 扩展，不是所有产品的全部功能：非 Jira multipart、二进制下载、GraphQL、JSM/插件特有 API 命名空间、完整 Confluence v2 专用工具等尚未实现。详见功能审查。

验证与生效

npm test --workspace=packages/pi-work-agent
npm exec --workspace=packages/pi-work-agent -- tsc --noEmit -p tsconfig.json

测试模拟 HTTP，不修改真实企业系统数据。构建后，本地加载包通过 /reload 或重启 pi 生效；独立安装的 npm 副本需要单独更新。本地修改不等于已发布新版本。

结构

• index.ts：初始化、工具注册、安全连接发现、关闭清理。
• config/：配置加载/验证和模板。
• connectors/：平台操作；json.ts 提供安全 JSON HTTP，Jira 另支持 multipart。
• core/registry.ts：类型安全和默认连接选择。
• core/tools.ts：跨系统用户确认队列、输出截断。
• tools/：Agent 参数 schema 与工具入口。
• tests/：模拟 HTTP/工具/入口回归测试。
• docs/CAPABILITIES.md：缺口审查和剩余边界。

MIT