ljdou-pi-work-agent

Pi enterprise collaboration extension for Jira, Confluence, GitLab and GitHub.

中文文档 · Capability audit and limitations

Installation and Configuration

npm install ljdou-pi-work-agent

The setup script creates ~/.pi/config/work-agent.yaml if missing and registers a global extension wrapper. For pi-managed package installation, use pi install /absolute/path/to/package or pi install npm:ljdou-pi-work-agent. Credentials belong in your private config, never in Git.

Use PI_WORK_AGENT_CONFIG to select an alternative YAML/JSON file. The shared simplified YAML parser does not support inline comments or inline arrays: put comments on separate lines and use multiline lists, or use JSON.

datasources:
  jira-prod:
    type: jira
    url: https://company.atlassian.net
    username: user@example.com
    token: replace-with-token
    apiVersion: "3"
    readOnly: false
    # Custom Cloud rich-text field IDs discovered from metadata
    # 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 applies only to tools of its own system type; other systems choose their first successfully connected connector. An explicit connector always wins, and wrong-type connections are rejected. work_list_connections shows safe operational metadata without credentials.

Capabilities

87 tools: Jira 26, Confluence 15, GitLab 23, GitHub 22, connection discovery 1. Tools remain registered when a connection fails, so calls report a meaningful connection error.

Jira (26)

• Reads: 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_comments, jira_get_worklogs, jira_get_link_types.
• Issue writes: jira_create_issue, jira_update_issue, jira_delete_issue, jira_transition_issue, jira_assign_issue.
• Comments: jira_add_comment, jira_update_comment, jira_delete_comment.
• Worklogs: jira_add_worklog, jira_update_worklog, jira_delete_worklog.
• Links/attachments: jira_link_issues, jira_delete_issue_link, jira_upload_attachment, jira_delete_attachment.
• Other APIs: jira_rest_request (Core /rest/api/2|3 and Agile /rest/agile/1.0).

Server/DC defaults to API v2. Cloud requires apiVersion: "3" and uses /search/jql with nextPageToken; Server uses startAt. Modern create metadata is paginated; older Server deployments can use their legacy metadata endpoint via REST.

Read issue/edit metadata before writing. Discover real custom field IDs, never guess development-plan/self-test IDs. fields.description replaces content; read and merge before appending. Cloud converts plain description/environment, comments and worklog comments into ADF paragraphs; explicit ADF passes unchanged. Custom rich-text fields require richTextFields or explicit ADF. Conversion does not parse Markdown/wiki markup. fields/update need non-empty objects and cannot contain the same field in both. State changes use transition IDs, not direct status assignment.

Worklog APIs can adjust remaining estimates; query: {"adjustEstimate":"leave"} preserves estimates. deleteSubtasks: true deletes all subtasks. Attachment uploads approve a local file snapshot (max 20MiB) by path, size and SHA-256.

Confluence (15)

• Reads: confluence_search, confluence_get_page, confluence_get_current_user, confluence_get_page_children, confluence_get_comments, confluence_get_labels.
• Pages: confluence_create_page, confluence_update_page, confluence_delete_page.
• Comments: confluence_add_comment, confluence_update_comment, confluence_delete_comment.
• Labels: confluence_add_label, confluence_remove_label.
• Other APIs: confluence_rest_request (/rest/api legacy v1 and Cloud /api/v2).

Dedicated tools use legacy REST v1, not v2; availability of legacy APIs depends on deployment. Cloud URL must include /wiki; Server/DC URL includes its actual context path. Page/comment bodies are storage XHTML, not Markdown. Updating a page requires complete title, body, and the current version; the request submits current+1. No hidden read/merge or retry after approval. Version conflict protects against concurrent edits. Delete/trash behavior and effects on descendants depend on deployment; the tool does not automatically purge or restore.

GitLab (23)

• Reads: gitlab_search_code, gitlab_get_file, gitlab_search_issue, gitlab_get_issue, gitlab_get_issue_notes, gitlab_get_current_user, gitlab_list_merge_requests, gitlab_get_merge_request.
• Issues: gitlab_create_issue, gitlab_update_issue, gitlab_delete_issue, gitlab_close_issue.
• Comments: gitlab_add_issue_note, gitlab_update_issue_note, gitlab_delete_issue_note.
• Repository files: gitlab_create_file, gitlab_update_file, gitlab_delete_file.
• MRs: gitlab_create_merge_request, gitlab_update_merge_request, gitlab_merge_merge_request.
• CI: gitlab_create_pipeline.
• Other APIs: gitlab_rest_request (/api/v4).

Use project-local IID, not global issue/MR ID. Project ID accepts numeric ID, raw group/project, or once-encoded path. Issue descriptions are Markdown and are replaced, not appended. Reopen using fields.state_event = "reopen". Reads support pagination; project-scoped search uses actual project endpoints. File reads default to HEAD, not an assumed main branch. File changes create commits on an explicit branch; pass options.last_commit_id for concurrency checks. options cannot override core explicit branch/content/message parameters. Merging requires expected head SHA; inspect review/check state first. Pipelines may deploy. Tokens/roles and protected branch rules remain authoritative.

GitHub (22)

• Reads: github_search_code, github_get_file, github_search_issue, github_get_current_user, github_get_issue, github_get_comments, github_list_pull_requests, github_get_pull_request.
• Issues: github_create_issue, github_update_issue (including close/reopen).
• Comments: github_add_comment, github_update_comment, github_delete_comment.
• Repository files: github_create_file, github_update_file, github_delete_file.
• PRs: github_create_pull_request, github_update_pull_request, github_merge_pull_request, github_review_pull_request.
• Actions: github_dispatch_workflow.
• Other APIs: github_rest_request (allowed same-host /repos, /user, /users, /orgs, /search, /notifications, /rate_limit paths).

File reads omit ref for the repository default branch. File writes base64-encode complete UTF-8 content and create commits; update/delete require the current blob SHA. Merge requires the expected PR head SHA; merged: false is a tool error, not success. Reviews target an explicit commit SHA. Actions dispatch requires explicit workflow/ref. There is no fake GitHub issue-delete REST tool; close via github_update_issue. Conversation comments differ from diff review comments (use REST for the latter).

Typical Issue Update

1. Discover connection with work_list_connections.
2. Read the issue; Jira additionally discovers custom fields/edit metadata.
3. Merge existing description with proposed plan/self-test content locally.
4. Call the relevant update tool and approve the exact target/payload.
5. Read back to verify success.

Example for GitLab:

{
  "connector": "gitlab-prod",
  "projectId": "group/project",
  "issueIid": "123",
  "fields": {"description": "Original requirement\n\nDevelopment plan: ...\nSelf-test scenarios: ..."}
}

Safety and Boundaries

• Every external write requires human TUI/RPC confirmation of connection URL, identity, operation, resources and payload. Print/JSON mode blocks writes; model-supplied confirmed flags cannot bypass approval.
• A shared queue across all systems serializes approval and submission, preventing overlapping dialogs. This is not a distributed lock against other clients.
• readOnly: true is enforced in connectors, including REST escape hatches. Platform permissions still govern actions.
• Raw REST uses raw JSON without rich-text conversion. Every non-GET requires approval (even POST searches). Identify actual bulk/admin scope before approval.
• URLs cannot contain credentials/query/fragment. Redirects, nested encoding and path traversal are blocked. Cancellation/timeouts are supported; no automatic write retries. Ambiguous results must be read back before retrying.
• Deletes/merges may be irreversible; commits/CI can notify, deploy or trigger automation. No multi-system transaction or rollback is promised. Sensitive file commits/uploads require explicit user intent.
• Output is bounded to 48KB/2000 lines, with full JSON in a private temporary file. Prefer field selection and pagination; temporary files require normal local cleanup.
• This is common workflow coverage plus JSON REST access, not every feature of every enterprise platform. Multipart uploads (except Jira), binary downloads, GraphQL, JSM/plugin-specific API namespaces and native full Confluence v2 workflow tools are not implemented. See the audit document.

Build and Test

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

Tests mock HTTP: no real enterprise records are changed. Build then /reload or restart pi for a locally loaded package. A separately installed npm copy must be updated separately. Source changes do not publish a release.

Structure

• index.ts: connection initialization, tool registration, discovery and shutdown cleanup.
• config/: private config loading/validation and example.
• connectors/: platform payloads and safe JSON transport (json.ts); Jira also supports multipart.
• core/registry.ts: typed/default connection selection.
• core/tools.ts: shared human approval queue and bounded output.
• tools/: model-facing schemas and platform operations.
• tests/: mock connector/tool/entry tests.
• docs/CAPABILITIES.md: audited coverage and remaining limitations.

MIT