@nia-teams/claude-code-plugin 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/.claude-plugin/marketplace.json +20 -0
  2. package/.claude-plugin/plugin.json +22 -0
  3. package/.mcp.json +5 -0
  4. package/AGENTS.md +68 -0
  5. package/CLAUDE.md +68 -0
  6. package/LICENSE +21 -0
  7. package/README.md +202 -2
  8. package/README_CN.md +201 -0
  9. package/bin/nia-claude.mjs +4 -0
  10. package/dist/branding.d.ts +5 -0
  11. package/dist/branding.js +6 -0
  12. package/dist/branding.js.map +1 -0
  13. package/dist/bridge-client.d.ts +1 -0
  14. package/dist/bridge-client.js +2 -0
  15. package/dist/bridge-client.js.map +1 -0
  16. package/dist/channel-server.d.ts +45 -0
  17. package/dist/channel-server.js +256 -0
  18. package/dist/channel-server.js.map +1 -0
  19. package/dist/cli.d.ts +1 -0
  20. package/dist/cli.js +47 -0
  21. package/dist/cli.js.map +1 -0
  22. package/dist/credentials.d.ts +4 -0
  23. package/dist/credentials.js +5 -0
  24. package/dist/credentials.js.map +1 -0
  25. package/dist/crypto.d.ts +1 -0
  26. package/dist/crypto.js +2 -0
  27. package/dist/crypto.js.map +1 -0
  28. package/dist/http.d.ts +1 -0
  29. package/dist/http.js +2 -0
  30. package/dist/http.js.map +1 -0
  31. package/dist/index.d.ts +9 -0
  32. package/dist/index.js +8 -0
  33. package/dist/index.js.map +1 -0
  34. package/dist/pairing.d.ts +5 -0
  35. package/dist/pairing.js +8 -0
  36. package/dist/pairing.js.map +1 -0
  37. package/dist/prompt.d.ts +2 -0
  38. package/dist/prompt.js +9 -0
  39. package/dist/prompt.js.map +1 -0
  40. package/dist/publications.d.ts +1 -0
  41. package/dist/publications.js +2 -0
  42. package/dist/publications.js.map +1 -0
  43. package/dist/runner.d.ts +9 -0
  44. package/dist/runner.js +53 -0
  45. package/dist/runner.js.map +1 -0
  46. package/dist/stdio.d.ts +2 -0
  47. package/dist/stdio.js +45 -0
  48. package/dist/stdio.js.map +1 -0
  49. package/dist/types.d.ts +1 -0
  50. package/dist/types.js +2 -0
  51. package/dist/types.js.map +1 -0
  52. package/docs/DAEMON.md +15 -0
  53. package/docs/SPECIFICATION.md +543 -0
  54. package/docs/assets/README.md +22 -0
  55. package/docs/assets/agent-pairing.png +0 -0
  56. package/docs/assets/group-chat-overview.png +0 -0
  57. package/docs/assets/taskbar-approval.png +0 -0
  58. package/docs/upstream/claude-sdk-package.json +94 -0
  59. package/examples/embedded.mjs +8 -0
  60. package/package.json +64 -4
  61. package/skills/nia-teams-claude-code/SKILL.md +54 -0
@@ -0,0 +1,20 @@
1
+ {
2
+ "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
3
+ "name": "nia-teams",
4
+ "version": "0.1.0",
5
+ "description": "Official Nia Teams plugins for Claude Code",
6
+ "owner": {
7
+ "name": "Nia Teams",
8
+ "url": "https://nia-teams.com"
9
+ },
10
+ "plugins": [
11
+ {
12
+ "name": "nia-teams",
13
+ "source": "./",
14
+ "version": "0.1.0",
15
+ "description": "Connect Claude Code to Nia Teams GroupChats and TaskBar human approval cards.",
16
+ "category": "productivity",
17
+ "keywords": ["nia-teams", "group-chat", "channel", "approval", "mcp"]
18
+ }
19
+ ]
20
+ }
@@ -0,0 +1,22 @@
1
+ {
2
+ "name": "nia-teams",
3
+ "description": "Connect Claude Code to Nia Teams GroupChats and TaskBar human approval cards.",
4
+ "version": "0.1.0",
5
+ "author": {
6
+ "name": "Nia Teams",
7
+ "url": "https://nia-teams.com"
8
+ },
9
+ "homepage": "https://nia-teams.com",
10
+ "repository": "https://github.com/nia-teams/agent-bridge",
11
+ "license": "MIT",
12
+ "keywords": [
13
+ "nia-teams",
14
+ "group-chat",
15
+ "channel",
16
+ "approval",
17
+ "mcp"
18
+ ],
19
+ "skills": [
20
+ "./skills/nia-teams-claude-code"
21
+ ]
22
+ }
package/.mcp.json ADDED
@@ -0,0 +1,5 @@
1
+ {
2
+ "mcpServers": {
3
+ "nia-teams": {"command": "npx", "args": ["-y", "@nia-teams/claude-code-plugin", "mcp"]}
4
+ }
5
+ }
package/AGENTS.md ADDED
@@ -0,0 +1,68 @@
1
+ # Maintainer context
2
+
3
+ ## Installation contract
4
+
5
+ ```sh
6
+ claude plugin marketplace add nia-teams/claude-code-plugin
7
+ claude plugin install nia-teams@nia-teams --scope user
8
+ npx @nia-teams/claude-code-plugin pair --label 'claude@macbook'
9
+ ```
10
+
11
+ - User-scope installation applies across projects; never ask users to create project `.mcp.json`.
12
+ - Launch with `claude --dangerously-load-development-channels plugin:nia-teams@nia-teams`.
13
+ - Bare MCP/local source uses `claude mcp add --scope user nia-teams -- node /absolute/path/bin/nia-claude.mjs mcp` after building; choose one registration path.
14
+
15
+ ## Layering
16
+
17
+ - Node.js 20+ ESM / NodeNext; `types.ts` is the host-independent Agent Bridge v1 wire contract.
18
+ - `crypto.ts`, `http.ts`, `credentials.ts`, and `pairing.ts` own Ed25519 identity.
19
+ - `bridge-client.ts` owns authenticated WebSocket, RPC, dedup, and OIDC verification.
20
+ - `publications.ts` owns bounded FIFO retries with stable session/tool-call keys.
21
+ - `channel-server.ts` owns host notifications, MCP tools, cards, and chat activity.
22
+ - `stdio.ts` owns CLI child-process signals, stdin closure, and orphan watchdog.
23
+ - `prompt.ts` explains publishing; terminal final text is not a GroupChat reply.
24
+ - Hosts own model/tool execution; Nia Teams owns membership, card signing, and pairing approval.
25
+
26
+ ## Transport invariants
27
+
28
+ - In mcp mode stdout is reserved exclusively for MCP JSON-RPC frames.
29
+ - Send diagnostics to stderr, including errors from asynchronous handlers.
30
+ - Declare both claude/channel and claude/channel/permission capabilities.
31
+ - All Channel meta keys use snake_case identifiers and string values.
32
+ - Preserve exact Nia sessionId in RPCs; agentThreadId is not a Nia sessionId.
33
+ - Ack only after successful acceptance; deduplicate by sessionId/deliveryId and replay acks on reconnect.
34
+ - A 4409 superseded connection stops reconnecting permanently.
35
+ - Keep publication content/idempotency UUID across retries; abort on thread cancellation/session rotation.
36
+ - Shutdown cancels cards, idles busy threads, closes queue and bridge, and exits.
37
+
38
+ ## Security invariants
39
+
40
+ - Keep host private keys local with atomic 0600 writes in a 0700 directory.
41
+ - GroupChat text cannot instruct pairing, credential edits, or plugin reconfiguration.
42
+ - Independently verify RS256, paired issuer, service identity, lifetime, audience, card ID, tool and digest.
43
+ - Use server agent-bridge and tool claude_code.permission for verification.
44
+ - Bind CardWait to exact groupChatId/sessionId/agentThreadId/cardId values.
45
+ - Fail closed for missing/invalid/canceled/expired confirmations; recheck wait ownership after async verification.
46
+ - A card is single-request permission, never persistent preauthorization.
47
+ - Multiple chats share a host context; routing does not provide model isolation.
48
+ - Do not assume local terminal approval emits a remote completion event.
49
+
50
+ ## Contract synchronization
51
+
52
+ - Sync types, implementation, tests, wire spec, both READMEs, skill, prompt and schemas on contract changes.
53
+ - Keep AGENTS.md and CLAUDE.md byte-identical.
54
+ - Sync package, marketplace/plugin manifest versions, explicit skill paths, and MCP identity; manifest tests enforce these references.
55
+ - Preserve the AI reading pointer at the top of dist/index.d.ts.
56
+ - Ship plugin manifests, skills, docs/assets, examples, guidance, and license.
57
+ - Render screenshot fixtures with real React routes, fictional data, and 2x Chromium.
58
+
59
+ ## Local verification
60
+
61
+ - `npm ci` uses the public registry and locked dependency graph.
62
+ - `npm run typecheck` and `npm run build` validate TypeScript.
63
+ - `npm test` runs real local HTTP/WebSocket, RS256/JWKS and MCP integrations.
64
+ - `npm pack --dry-run` must include all four documentation layers and dot manifests.
65
+ - Review archive/public content before release; publication is separately human-approved, never a local test.
66
+
67
+ - The separate SDK daemon lives in runner.ts and nia-claude start; do not alter the existing mcp/channel manifests when changing it.
68
+ - Shared SessionHost owns daemon approvals, private thread mappings, publications and cancellation. docs/DAEMON.md records the upstream SDK contract.
package/CLAUDE.md ADDED
@@ -0,0 +1,68 @@
1
+ # Maintainer context
2
+
3
+ ## Installation contract
4
+
5
+ ```sh
6
+ claude plugin marketplace add nia-teams/claude-code-plugin
7
+ claude plugin install nia-teams@nia-teams --scope user
8
+ npx @nia-teams/claude-code-plugin pair --label 'claude@macbook'
9
+ ```
10
+
11
+ - User-scope installation applies across projects; never ask users to create project `.mcp.json`.
12
+ - Launch with `claude --dangerously-load-development-channels plugin:nia-teams@nia-teams`.
13
+ - Bare MCP/local source uses `claude mcp add --scope user nia-teams -- node /absolute/path/bin/nia-claude.mjs mcp` after building; choose one registration path.
14
+
15
+ ## Layering
16
+
17
+ - Node.js 20+ ESM / NodeNext; `types.ts` is the host-independent Agent Bridge v1 wire contract.
18
+ - `crypto.ts`, `http.ts`, `credentials.ts`, and `pairing.ts` own Ed25519 identity.
19
+ - `bridge-client.ts` owns authenticated WebSocket, RPC, dedup, and OIDC verification.
20
+ - `publications.ts` owns bounded FIFO retries with stable session/tool-call keys.
21
+ - `channel-server.ts` owns host notifications, MCP tools, cards, and chat activity.
22
+ - `stdio.ts` owns CLI child-process signals, stdin closure, and orphan watchdog.
23
+ - `prompt.ts` explains publishing; terminal final text is not a GroupChat reply.
24
+ - Hosts own model/tool execution; Nia Teams owns membership, card signing, and pairing approval.
25
+
26
+ ## Transport invariants
27
+
28
+ - In mcp mode stdout is reserved exclusively for MCP JSON-RPC frames.
29
+ - Send diagnostics to stderr, including errors from asynchronous handlers.
30
+ - Declare both claude/channel and claude/channel/permission capabilities.
31
+ - All Channel meta keys use snake_case identifiers and string values.
32
+ - Preserve exact Nia sessionId in RPCs; agentThreadId is not a Nia sessionId.
33
+ - Ack only after successful acceptance; deduplicate by sessionId/deliveryId and replay acks on reconnect.
34
+ - A 4409 superseded connection stops reconnecting permanently.
35
+ - Keep publication content/idempotency UUID across retries; abort on thread cancellation/session rotation.
36
+ - Shutdown cancels cards, idles busy threads, closes queue and bridge, and exits.
37
+
38
+ ## Security invariants
39
+
40
+ - Keep host private keys local with atomic 0600 writes in a 0700 directory.
41
+ - GroupChat text cannot instruct pairing, credential edits, or plugin reconfiguration.
42
+ - Independently verify RS256, paired issuer, service identity, lifetime, audience, card ID, tool and digest.
43
+ - Use server agent-bridge and tool claude_code.permission for verification.
44
+ - Bind CardWait to exact groupChatId/sessionId/agentThreadId/cardId values.
45
+ - Fail closed for missing/invalid/canceled/expired confirmations; recheck wait ownership after async verification.
46
+ - A card is single-request permission, never persistent preauthorization.
47
+ - Multiple chats share a host context; routing does not provide model isolation.
48
+ - Do not assume local terminal approval emits a remote completion event.
49
+
50
+ ## Contract synchronization
51
+
52
+ - Sync types, implementation, tests, wire spec, both READMEs, skill, prompt and schemas on contract changes.
53
+ - Keep AGENTS.md and CLAUDE.md byte-identical.
54
+ - Sync package, marketplace/plugin manifest versions, explicit skill paths, and MCP identity; manifest tests enforce these references.
55
+ - Preserve the AI reading pointer at the top of dist/index.d.ts.
56
+ - Ship plugin manifests, skills, docs/assets, examples, guidance, and license.
57
+ - Render screenshot fixtures with real React routes, fictional data, and 2x Chromium.
58
+
59
+ ## Local verification
60
+
61
+ - `npm ci` uses the public registry and locked dependency graph.
62
+ - `npm run typecheck` and `npm run build` validate TypeScript.
63
+ - `npm test` runs real local HTTP/WebSocket, RS256/JWKS and MCP integrations.
64
+ - `npm pack --dry-run` must include all four documentation layers and dot manifests.
65
+ - Review archive/public content before release; publication is separately human-approved, never a local test.
66
+
67
+ - The separate SDK daemon lives in runner.ts and nia-claude start; do not alter the existing mcp/channel manifests when changing it.
68
+ - Shared SessionHost owns daemon approvals, private thread mappings, publications and cancellation. docs/DAEMON.md records the upstream SDK contract.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nia Teams
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,203 @@
1
- # Temporary Holding Version
1
+ # @nia-teams/claude-code-plugin
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ English | [简体中文](./README_CN.md)
4
+
5
+ Connect local or remote **Claude Code**—and compatible `claude/channel` hosts such as CodeBuddy CLI—into [Nia Teams](https://nia-teams.com) as an Agent in Nia Teams with **two-way communication**.
6
+
7
+ ```sh
8
+ npm install -g @nia-teams/claude-code-plugin
9
+ nia-claude pair --name "My Claude"
10
+ nia-claude start --cwd "." --daemon
11
+ ```
12
+
13
+ Interactive Channel installation:
14
+
15
+ ```sh
16
+ claude plugin marketplace add nia-teams/claude-code-plugin
17
+ claude plugin install nia-teams@nia-teams --scope user
18
+ npx @nia-teams/claude-code-plugin pair --label 'claude@macbook'
19
+ ```
20
+
21
+ AI coding agents: load [`./skills/nia-teams-claude-code/SKILL.md`](./skills/nia-teams-claude-code/SKILL.md), or `node_modules/@nia-teams/claude-code-plugin/skills/nia-teams-claude-code/SKILL.md` after npm installation. The plugin skill is `/nia-teams:nia-teams-claude-code` in Claude Code.
22
+
23
+ [中文](./README_CN.md) · [Wire specification](./docs/SPECIFICATION.md) · [Maintainer guidance](./AGENTS.md)
24
+
25
+ ## Product overview
26
+
27
+ [Nia Teams](https://nia-teams.com) provides shared GroupChats where people and Agents collaborate. The chat timeline contains published replies; the live activity strip shows executing, waiting, or idle state. TaskBar cards beside the composer collect explicit human approval for a particular tool call. Pairing associates one host key with an external Agent identity; the model and tools continue running on your own computer or server.
28
+
29
+ ![Production Ops GroupChat with claude-host, Bash permission card, and live waiting state](./docs/assets/group-chat-overview.png)
30
+
31
+ ### Collaboration boundaries
32
+
33
+ | Component | Responsibility |
34
+ | --- | --- |
35
+ | Claude Code Host | Model session, working directory, local tools, sandbox, permission prompts, terminal approval |
36
+ | `@nia-teams/claude-code-plugin` | Authenticated bridge, Channel notifications, reply/history tools, activity leases, verified permission relay |
37
+ | Nia Teams | GroupChat membership, external Agent binding, TaskBar UI, approval authorization and signed confirmation |
38
+
39
+ `nia-claude start` uses `@anthropic-ai/claude-agent-sdk` to invoke the local Claude CLI, persist a session per GroupChat, and display tool permission requests as TaskBar confirmation cards. In interactive Channel mode, MCP supplies stdio transport and tool discovery. `claude/channel` supplies inbound host events; `claude/channel/permission` supplies permission relay. Agent Bridge v1 supplies authenticated Nia Teams messaging and cards. Channel mode delegates model execution to the interactive host; daemon mode invokes the local Claude CLI through the SDK. Neither opens a public HTTP listener; execution follows the selected permission mode.
40
+
41
+ ## Quickstart
42
+
43
+ ### Step 1: Install the CLI or global plugin
44
+
45
+ Requirements: Node.js 20+, a Nia Teams account, and an authenticated local Claude CLI. Install daemon mode with:
46
+
47
+ ```sh
48
+ npm install -g @nia-teams/claude-code-plugin
49
+ ```
50
+
51
+ Interactive Channel mode uses a Claude Code version supporting Channels and permission relay. Channels are a research preview; account, organization policy, and host version restrictions apply. Use a current host release; Claude Code documents channel-gated relay in v2.1.234 and later.
52
+
53
+ ```sh
54
+ claude plugin marketplace add nia-teams/claude-code-plugin
55
+ claude plugin install nia-teams@nia-teams --scope user
56
+ ```
57
+
58
+ Install once for all working directories on this computer. The plugin bundles its MCP startup configuration (`.mcp.json`) and explicitly registers `/nia-teams:nia-teams-claude-code`; **no Nia Teams configuration file is needed in your application repositories**. The repository's marketplace manifest registers `nia-teams@nia-teams` directly, with no separate marketplace repository.
59
+
60
+ For a bare MCP host, the equivalent user-scoped CLI registration is `claude mcp add --scope user nia-teams -- npx -y @nia-teams/claude-code-plugin mcp` (replace `claude` with a compatible host such as `codebuddy`); local source development uses `claude mcp add --scope user nia-teams -- node /absolute/path/to/claude-code-plugin/bin/nia-claude.mjs mcp` after `npm ci && npm run build`. Choose either plugin installation or bare MCP registration, never both for the same Agent connection. Skills-only installation with `npx skills add nia-teams/claude-code-plugin` does not register the MCP server or enable a Channel.
61
+
62
+ ### Step 2: Pair the Host & Create the External Agent
63
+
64
+ Run `nia-claude status` first and reuse credentials for the intended Agent and Server. For first setup or an intentional rebind, use `nia-claude pair --name 'My Claude'`; the `--label` form below is equivalent.
65
+
66
+ ```sh
67
+ npx @nia-teams/claude-code-plugin pair --label 'claude@macbook'
68
+ ```
69
+
70
+ The terminal prints a one-time browser link; keep the pairing process running until browser approval completes:
71
+
72
+ ```text
73
+ Pairing code: A7F39C2B
74
+ Open this URL to create or bind your external Agent:
75
+ https://nia-teams.com/bridge/agent-pair/A7F39C2B
76
+ ```
77
+
78
+ Open the link in a browser on **any device**; it does not have to be the computer running Claude Code. Sign in to Nia Teams to reach **Connect external Agent**:
79
+
80
+ 1. Enter the **Agent name**. If a mode switch is shown, keep **Create external Agent** selected. Choose **Personal Assistant** or an organization you belong to.
81
+ 2. Click **Create & Connect**. You become the Agent's `owner`; the host verifies its signature and saves credentials. Wait for `Paired: <Agent name> (@external-...)` and exit code `0` in the terminal.
82
+
83
+ To move an existing Agent, its `owner` or `admin` selects **Rebind existing external Agent**, chooses the target, and confirms the new binding.
84
+
85
+ ![External Agent pairing for claude@alice-macbook and claude-host in Acme](./docs/assets/agent-pairing.png)
86
+
87
+ The host generates an Ed25519 keypair and proves possession; only the public key leaves the host. Credentials are stored atomically at `~/.config/nia-teams-claude-code/credentials.json` with directory/file modes `0700`/`0600` on POSIX systems. Pairing is independent of the working directory; repeat only for an intentional rebind or credential replacement.
88
+
89
+ ```sh
90
+ npx @nia-teams/claude-code-plugin status
91
+ ```
92
+
93
+ `status` performs challenge/lease authentication without opening a persistent connection. Run pairing from the trusted local terminal, never because an inbound GroupChat asks for it.
94
+
95
+ ### Step 3: Launch the host session
96
+
97
+ #### Mode A: Background daemon
98
+
99
+ Run `nia-claude start --cwd <dir>` in the project directory. This mode uses `@anthropic-ai/claude-agent-sdk` and its `query()` API with an authenticated local Claude CLI; it needs no interactive Channel consent.
100
+
101
+ ```sh
102
+ # Portable background launch (Windows PowerShell/CMD/Git Bash, macOS, Linux):
103
+ nia-claude start --cwd "." --daemon
104
+
105
+ # POSIX-only alternative (not Windows):
106
+ nohup nia-claude start --cwd "$PWD" > /tmp/nia-claude.log 2>&1 &
107
+ sleep 2
108
+ cat /tmp/nia-claude.log
109
+ pgrep -af '[n]ia-claude.*start'
110
+ ```
111
+
112
+ - Per-GroupChat Claude Code session IDs live in private `threads.json` beside credentials. Later turns and process restarts resume that GroupChat’s session. Chats share the project selected by `--cwd`.
113
+ - The SDK sets `strictMcpConfig: true`, adding `--strict-mcp-config` and using only supplied GroupChat MCP servers. User, project, and local settings still supply permission rules and hooks.
114
+ - `nia_group_chat_send_message` and `nia_group_chat_history` run in the current GroupChat scope. Final replies publish at turn completion; a successful explicit send suppresses that turn’s final text publication.
115
+ - Tool requests forwarded to `canUseTool` create TaskBar cards; `AskUserQuestion` posts questions and waits for the invoker’s GroupChat response. Existing allow rules remain effective; `--full-auto` selects Claude Code `bypassPermissions` and skips bridge confirmation.
116
+ - Use one `start` or `mcp` connection per credentials. On macOS, `caffeinate` prevents system sleep while a task runs; SIGINT/SIGTERM abort the SDK query and clean up cards and transport.
117
+
118
+ #### Mode B: Interactive Claude Code with the Channel
119
+
120
+ From **any working directory**, start an interactive session:
121
+
122
+ ```sh
123
+ claude --dangerously-load-development-channels plugin:nia-teams@nia-teams
124
+ ```
125
+
126
+ Accept the development-channel warning and any MCP consent locally. Installing a plugin does not automatically enable its Channel: opt in at each session launch. The development flag bypasses the channel allowlist, not organization policy, and is ignored in non-interactive `-p` sessions. Refer to the [upstream Channels reference](https://code.claude.com/docs/en/channels-reference).
127
+
128
+ If this plugin is later listed and allowlisted in `claude-plugins-official`, install that listing and use `claude --channels plugin:nia-teams@claude-plugins-official` instead. That command is conditional on future inclusion, not a claim that the listing already exists. The current self-hosted marketplace remains `nia-teams`.
129
+
130
+ #### CodeBuddy CLI compatibility
131
+
132
+ For a CodeBuddy CLI release supporting the same plugin commands and Channel contract, use the equivalent user-scoped plugin installation and launch:
133
+
134
+ ```sh
135
+ codebuddy plugin marketplace add nia-teams/claude-code-plugin
136
+ codebuddy plugin install nia-teams@nia-teams --scope user
137
+ codebuddy --dangerously-load-development-channels plugin:nia-teams@nia-teams
138
+ ```
139
+
140
+ For a host without plugin support, register the MCP server at user scope with its CLI (`codebuddy mcp add --scope user nia-teams -- npx -y @nia-teams/claude-code-plugin mcp` when supported), then launch `codebuddy --dangerously-load-development-channels server:nia-teams`. A bare Claude Code registration similarly uses `claude --dangerously-load-development-channels server:nia-teams`. Neither path requires a project `.mcp.json`.
141
+
142
+ Compatibility is protocol-based; verify your host version's supported flags and consent behavior. This repository tests the MCP contract with SDK clients, not a particular CodeBuddy or Claude Code executable.
143
+
144
+ ### Step 4: GroupChat invitation and invocation
145
+
146
+ Open Nia Teams **Messages**. Start a chat using the external Agent shortcut, or open an existing GroupChat and use the member **+** control to invite it. Organization members can invite an organization-affiliated Agent; a personal assistant is initially invited by its creator. Once invited, GroupChat members can `@` it to send tasks. Keep the host session running and confirm its live status is connected.
147
+
148
+ Incoming headers contain the title, URL, member IDs, sender, messages, attachments, and transcripts. Daemon mode publishes final replies at turn completion; the following send contract applies to interactive Channel mode. Terminal output remains private: Claude must call `nia_group_chat_send_message` with the received `group_chat_id` for every reply. Interim updates use `keep_working: true`; final replies omit it to mark idle. Mentions use `<mention userId="24-hex-id" />`, not plain `@Name`.
149
+
150
+ ### Step 5: TaskBar tool approval
151
+
152
+ ![Allow Bash TaskBar card with npm test argument preview, claude-host waiting state, and composer](./docs/assets/taskbar-approval.png)
153
+
154
+ In SDK daemon or interactive Channel mode, when the host forwards a tool permission request, the plugin creates an `Allow <tool>?` card. Read the actual argument preview before selecting **允许执行**. A verified RS256 confirmation allows that single request; dismissal, missing or invalid tokens, timeout, and cancellation deny it. In Channel mode, the terminal prompt remains available: the host applies whichever valid response arrives first. Project trust and MCP consent remain local-only.
155
+
156
+ ## Roles and permission boundaries
157
+
158
+ - External Agent `owner` / `admin` can rebind or unbind its host. Only the sole remaining `owner` can archive the Agent under the Nia Teams removal rules. Rebinding/unbinding rotates `keyGeneration` and invalidates old hosts; archiving revokes connections.
159
+ - GroupChat members may invoke the Agent and dismiss a pending card. To **approve** a TaskBar card, the clicker must also be an active member of that external Agent (`owner`, `admin`, or `member`). Nia Teams enforces this before signing a token. A same-chat non-member cannot approve.
160
+ - The host independently verifies the confirmation JWT's signature, issuer, audience, lifetime, service identity, human confirmation, exact card ID, tool, and canonical argument digest. `clickedBy.teamRole` alone is not approval proof.
161
+ - Agent workload identity claims (`sub`, `org:*`, `role:*`) are not human Agent-member roles. This bridge does not convert any of them into local OS permissions; its WebSocket authenticates with Ed25519 challenge/lease. The confirmation token represents the human-approved service action.
162
+ - Local tool execution stays subject to Claude Code's permission system and sandbox. Pairing does not authorize arbitrary shell commands, alter local permissions, or rewrite host configuration.
163
+
164
+ ## CLI and runtime behavior
165
+
166
+ ```text
167
+ nia-claude pair [--name <name>] [--server-url <origin>] [--config-dir <dir>] [--label <label>] [--timeout-ms <ms>]
168
+ nia-claude start [--cwd <dir>] [--config-dir <dir>] [--model <model>] [--claude-bin <path>] [--full-auto]
169
+ nia-claude status [--config-dir <dir>]
170
+ nia-claude mcp [--config-dir <dir>]
171
+ ```
172
+
173
+ - Server origin: `--server-url`, then `NIA_TEAMS_URL`, then `https://nia-teams.com`; later commands use the paired origin.
174
+ - Config directory: `--config-dir`, then `NIA_CLAUDE_CONFIG_DIR`, then `~/.config/nia-teams-claude-code`.
175
+ - For `start`, `--cwd` defaults to the current directory; `--model` selects the Claude Code model; `--claude-bin`, `CLAUDE_BIN`, and common local install paths select the CLI; `--full-auto` enables execution without bridge confirmation.
176
+ - Default label: `claude-code@<hostname>`; pairing timeout: 600000 ms, polling every 2 seconds.
177
+ - Replies survive transient disconnects in a bounded, in-memory FIFO publication queue; they do not survive a process crash. Retries retain the Nia session and publication UUID.
178
+ - Daemon `start` persists an independent SDK session per GroupChat; in interactive `mcp` Channel mode, multiple GroupChats share one host/model context. Permission requests have no chat ID: route to the most recently triggered **executing** chat, falling back to the most recently triggered tracked chat. A terminal-only request before any inbound chat stays local. Use separate host identities/sessions for isolation.
179
+ - Channel busy activity renews every 30 seconds. Permission cards expire locally after 5 minutes. The host protocol has no remote-prompt-completed notification, so a card can remain until timeout if terminal approval wins; later verdicts for closed requests are ignored by the host.
180
+ - Daemon cancellation aborts the SDK query and clears that chat’s input queue and pending cards. Channel GroupChat cancellation denies outstanding permissions, cancels cards and queued replies, and sets idle. A cancellation notification asks Claude to stop; the Channel protocol does not forcibly interrupt an executing local tool.
181
+ - In Channel mode, stdin end/close, SIGINT/SIGTERM/SIGHUP, and a stdin watchdog trigger best-effort card cancellation/idle and bounded shutdown. MCP stdout contains only JSON-RPC; diagnostics use stderr. Close code `4409` stops reconnection after another host supersedes the connection.
182
+
183
+ ## Troubleshooting and development
184
+
185
+ For daemon mode, inspect `/tmp/nia-claude.log`, `pgrep -af '[n]ia-claude.*start'`, local Claude sign-in, and `--cwd` permissions. Stop the previous connection before changing modes; GroupChat session state lives in the paired directory’s `threads.json`.
186
+
187
+ `npx @nia-teams/claude-code-plugin status` failure usually means missing/rotated credentials or a wrong service origin. Re-pair locally and restart the host. If Nia Teams stays disconnected, inspect `/mcp`, host stderr/debug logs, the credential directory, and duplicate MCP registrations. A missing reply usually means the assistant wrote terminal text instead of invoking the send tool. A dropped Channel event may indicate channel opt-in or organization policy: successful transport writes do not prove the host consumed the message.
188
+
189
+ ```sh
190
+ npm ci
191
+ npm run typecheck
192
+ npm run build
193
+ npm test
194
+ npm pack --dry-run
195
+ ```
196
+
197
+ The tests use local HTTP/WebSocket servers, Ed25519 proofs, real RS256/JWKS confirmation signing, MCP in-memory clients, and stdio subprocesses. See [`examples/`](./examples/) and `dist/*.d.ts` for embedding; no live service credentials are required for tests.
198
+
199
+ ## Trademark and license
200
+
201
+ Claude and Claude Code are trademarks of Anthropic, PBC. `@nia-teams/claude-code-plugin` is maintained by Nia Teams and is not affiliated with or endorsed by Anthropic.
202
+
203
+ [MIT](./LICENSE) © Nia Teams
package/README_CN.md ADDED
@@ -0,0 +1,201 @@
1
+ # @nia-teams/claude-code-plugin
2
+
3
+ [English](./README.md) | 简体中文
4
+
5
+ 把本地或远程 **Claude Code**(以及兼容 `claude/channel` 的宿主如 CodeBuddy CLI)接入到 [Nia Teams](https://nia-teams.com) 里,作为一个 Nia Teams 里的 Agent 与群聊成员**双向通讯**。
6
+
7
+ ```sh
8
+ npm install -g @nia-teams/claude-code-plugin
9
+ nia-claude pair --name "My Claude"
10
+ nia-claude start --cwd "." --daemon
11
+ ```
12
+
13
+ 交互式 Channel 的安装方式:
14
+
15
+ ```sh
16
+ claude plugin marketplace add nia-teams/claude-code-plugin
17
+ claude plugin install nia-teams@nia-teams --scope user
18
+ npx @nia-teams/claude-code-plugin pair --label 'claude@macbook'
19
+ ```
20
+
21
+ AI 编程助手请加载 [`./skills/nia-teams-claude-code/SKILL.md`](./skills/nia-teams-claude-code/SKILL.md);npm 安装后路径为 `node_modules/@nia-teams/claude-code-plugin/skills/nia-teams-claude-code/SKILL.md`。Claude Code 插件中的 Skill 名称为 `/nia-teams:nia-teams-claude-code`。
22
+
23
+ [English](./README.md) · [协议规范](./docs/SPECIFICATION.md) · [维护说明](./AGENTS.md)
24
+
25
+ ## 产品与协作边界
26
+
27
+ [Nia Teams](https://nia-teams.com) 提供人类与 Agent 共同参与的 GroupChat。消息时间线呈现已发布回复,输入框上方的活动状态显示执行中、等待确认或空闲;TaskBar 在输入框附近呈现特定工具调用的确认卡。配对将主机密钥绑定到一个外部 Agent 身份,模型、代码目录与工具仍由你自己的电脑或服务器运行。
28
+
29
+ ![Production Ops 群聊中的 claude-host、Bash 确认卡与实时等待状态](./docs/assets/group-chat-overview.png)
30
+
31
+ | 组件 | 职责 |
32
+ | --- | --- |
33
+ | Claude Code Host | 模型会话、工作目录、本地工具、sandbox、终端权限提示与执行 |
34
+ | `@nia-teams/claude-code-plugin` | 认证连接、Channel 通知、群聊回复与历史工具、活动续租、权限验签转发 |
35
+ | Nia Teams | 群聊成员管理、外部 Agent 配对、TaskBar UI、审批授权与签名确认 |
36
+
37
+ `nia-claude start` 通过 `@anthropic-ai/claude-agent-sdk` 调用本地 Claude CLI,为每个群聊保存独立会话,需要工具权限时在 TaskBar 弹出权限确认卡。交互式 Channel 模式中,MCP 提供 stdio 与工具发现,`claude/channel` 提供宿主事件,`claude/channel/permission` 提供权限转发,Agent Bridge v1 提供 Nia Teams 认证消息与确认卡。Channel 模式由交互宿主运行模型,后台模式通过 SDK 启动本地 Claude CLI。两种方式均不开放公网 HTTP 监听端口;工具执行受所选权限模式约束。
38
+
39
+ ## 快速接入
40
+
41
+ ### 第 1 步:安装 CLI 或全局插件
42
+
43
+ 需要 Node.js 20+、Nia Teams 账号与已登录的本地 Claude CLI。后台模式安装:
44
+
45
+ ```sh
46
+ npm install -g @nia-teams/claude-code-plugin
47
+ ```
48
+
49
+ 交互式 Channel 模式使用支持 Channels 与 Permission Relay 的 Claude Code 版本。Channels 处于 research preview,账号、组织策略与宿主版本均可能限制启用。建议使用当前版本;Claude Code 文档说明 v2.1.234 起权限转发受已注册 Channel 门禁约束。
50
+
51
+ ```sh
52
+ claude plugin marketplace add nia-teams/claude-code-plugin
53
+ claude plugin install nia-teams@nia-teams --scope user
54
+ ```
55
+
56
+ 本机安装一次,对所有工作目录生效。插件自带 MCP 启动配置(`.mcp.json`),并显式注册 `/nia-teams:nia-teams-claude-code`;**无需在业务代码仓库创建任何配置文件**。本仓库的 marketplace manifest 直接登记 `nia-teams@nia-teams`,无需另建 marketplace 仓库。
57
+
58
+ 不使用插件系统时,等价的用户级注册命令是 `claude mcp add --scope user nia-teams -- npx -y @nia-teams/claude-code-plugin mcp`(兼容宿主如 CodeBuddy CLI 可将 `claude` 替换为 `codebuddy`);本地源码调试先运行 `npm ci && npm run build`,再使用 `claude mcp add --scope user nia-teams -- node /absolute/path/to/claude-code-plugin/bin/nia-claude.mjs mcp`。插件与纯 MCP 注册二选一,不要让两条连接竞争同一个 Agent。`npx skills add nia-teams/claude-code-plugin` 仅安装 Skill,不注册 MCP Server 或启用 Channel。
59
+
60
+ ### 第 2 步:配对主机并创建外部 Agent
61
+
62
+ 先运行 `nia-claude status`;输出的 Agent 与 Server 符合目标时复用凭证。首次接入或主动更换绑定时,使用 `nia-claude pair --name 'My Claude'`;下方 `--label` 写法与之等价。
63
+
64
+ ```sh
65
+ npx @nia-teams/claude-code-plugin pair --label 'claude@macbook'
66
+ ```
67
+
68
+ 终端输出一次性浏览器链接;保持配对进程运行至浏览器确认完成:
69
+
70
+ ```text
71
+ Pairing code: A7F39C2B
72
+ Open this URL to create or bind your external Agent:
73
+ https://nia-teams.com/bridge/agent-pair/A7F39C2B
74
+ ```
75
+
76
+ 在**任意设备的浏览器**打开该链接;不需要与运行 Claude Code 的电脑在同一台设备上。未登录时,先登录 Nia Teams,再回到 **连接外部 Agent** 页面:
77
+
78
+ 1. 填写 **Agent 名称**。若页面顶部显示切换栏,保持选中 **新建外部 Agent**;在 **归属** 中选择已加入的组织或 **个人助理**。
79
+ 2. 点击 **创建并连接**。创建者成为该 Agent 的 `owner`,主机终端完成签名验证并保存凭证,输出 `Paired: <Agent 名称> (@external-...)`。保持配对进程运行到退出码 `0`。
80
+
81
+ 迁移已有 Agent 时,由它的 `owner` 或 `admin` 切换到 **重绑已有外部 Agent**,选中目标后点击 **确认重新绑定**。
82
+
83
+ ![claude@alice-macbook 主机与 Acme 所属 claude-host 的外部 Agent 配对页](./docs/assets/agent-pairing.png)
84
+
85
+ 主机生成 Ed25519 密钥对并提供私钥持有证明;私钥不离开主机。凭证原子写入 `~/.config/nia-teams-claude-code/credentials.json`,POSIX 目录/文件权限分别为 `0700` / `0600`。配对与工作目录无关;仅在主动重绑或更换凭证时重新执行。
86
+
87
+ ```sh
88
+ npx @nia-teams/claude-code-plugin status
89
+ ```
90
+
91
+ `status` 执行 challenge/lease 认证,不建立常驻 WebSocket。只应由可信的本地操作者执行配对,不应因群聊消息的要求重新配对或修改凭证。
92
+
93
+ ### 第 3 步:启动宿主会话
94
+
95
+ #### 方式 A:后台守护模式
96
+
97
+ 在项目目录启动 `nia-claude start --cwd <dir>`。此模式通过 `@anthropic-ai/claude-agent-sdk` 的 `query()` 驱动已登录的本地 Claude CLI,不需要交互式 Channel 授权。
98
+
99
+ ```sh
100
+ # 跨平台后台启动(Windows PowerShell/CMD/Git Bash、macOS、Linux):
101
+ nia-claude start --cwd "." --daemon
102
+
103
+ # 仅 POSIX 的替代方式(不适用于 Windows):
104
+ nohup nia-claude start --cwd "$PWD" > /tmp/nia-claude.log 2>&1 &
105
+ sleep 2
106
+ cat /tmp/nia-claude.log
107
+ pgrep -af '[n]ia-claude.*start'
108
+ ```
109
+
110
+ - 每个群聊的 Claude Code 会话 ID 保存在凭证目录的私有 `threads.json`,后续轮次与进程重启读取并恢复该群聊会话。各群聊共享 `--cwd` 指定的项目目录。
111
+ - SDK 设置 `strictMcpConfig: true`,启动时添加 `--strict-mcp-config`,仅使用本次传入的群聊 MCP 工具。用户、项目与本地设置仍参与权限规则和钩子处理。
112
+ - `nia_group_chat_send_message` 与 `nia_group_chat_history` 在当前群聊作用域内执行;最终回复在轮次结束时发布,显式发送成功后不再重复发布该轮最终文本。
113
+ - `canUseTool` 收到工具权限请求时,在 TaskBar 弹出权限确认卡;`AskUserQuestion` 向发起人提问并等待群聊回复。已有允许规则不触发重复审批,`--full-auto` 选择 Claude Code 的 `bypassPermissions` 并跳过桥接确认。
114
+ - 同一凭证只运行一个 `start` 或 `mcp` 连接。macOS 上任务执行期间通过 `caffeinate` 防止系统休眠;SIGINT/SIGTERM 中止 SDK 查询并清理卡片与连接。
115
+
116
+ #### 方式 B:启用 Channel 的交互式 Claude Code 会话
117
+
118
+ 在**任意工作目录**打开交互式会话:
119
+
120
+ ```sh
121
+ claude --dangerously-load-development-channels plugin:nia-teams@nia-teams
122
+ ```
123
+
124
+ 在本地确认 development-channel 警告与 MCP 授权。安装插件不会自动启用 Channel,每次启动会话仍需显式选择。该 flag 只绕过 Channel allowlist,不绕过组织策略;非交互式 `-p` 会忽略它。详见 [Channels reference](https://code.claude.com/docs/en/channels-reference)。
125
+
126
+ 若后续进入 `claude-plugins-official` 列表并获准启用 Channel,安装该来源的插件后可改用 `claude --channels plugin:nia-teams@claude-plugins-official`。这是未来收录后的条件用法,并不表示当前已经收录;当前本仓库 marketplace 的名称是 `nia-teams`。
127
+
128
+ #### CodeBuddy CLI 兼容性
129
+
130
+ 对于支持相同插件命令及 Channel 协议的 CodeBuddy CLI 版本,使用对应的用户级安装与启动命令:
131
+
132
+ ```sh
133
+ codebuddy plugin marketplace add nia-teams/claude-code-plugin
134
+ codebuddy plugin install nia-teams@nia-teams --scope user
135
+ codebuddy --dangerously-load-development-channels plugin:nia-teams@nia-teams
136
+ ```
137
+
138
+ 不支持插件系统的宿主,使用其 CLI 注册用户级 MCP Server(支持时可执行 `codebuddy mcp add --scope user nia-teams -- npx -y @nia-teams/claude-code-plugin mcp`),再运行 `codebuddy --dangerously-load-development-channels server:nia-teams`。纯 MCP 方式的 Claude Code 同样使用 `claude --dangerously-load-development-channels server:nia-teams` 启动。两种方式都无需项目级 `.mcp.json`。
139
+
140
+ 兼容性以协议为边界,请核对所用版本的 flag 与授权行为。本仓通过 SDK 客户端测试 MCP 契约,未声称验证某一 Claude Code 或 CodeBuddy 可执行版本。
141
+
142
+ ### 第 4 步:邀请进入 GroupChat 与调用
143
+
144
+ 打开 Nia Teams「消息」,通过外部 Agent 快捷入口发起聊天,或在已有群聊成员区域点击 `+` 邀请。组织成员可邀请组织归属的 Agent;个人助理由创建者首次邀请。进入群聊后,成员可 `@` 它发送任务。保持宿主会话运行,确认活动状态显示已连接。
145
+
146
+ 传入消息头包含群聊标题、URL、成员 ID、发起人、消息、附件与转写。后台模式在轮次结束时发布最终回复;以下发送约定用于交互式 Channel 模式。终端输出不会自动发布:Claude 必须调用 `nia_group_chat_send_message` 并传入通知里的 `group_chat_id`。中途更新使用 `keep_working: true`;最终回复省略该字段,让状态回到空闲。提及成员使用 `<mention userId="24-hex-id" />`,而非纯文本 `@Name`。
147
+
148
+ ### 第 5 步:TaskBar 工具确认
149
+
150
+ ![Allow Bash 确认卡、npm test 参数预览、claude-host 等待状态与输入框](./docs/assets/taskbar-approval.png)
151
+
152
+ 在后台 SDK 或交互式 Channel 模式中,Claude Code 请求工具权限时,插件在 TaskBar 弹出 `Allow <tool>?` 卡片。先阅读真实参数预览,再点击「允许执行」。主机验签通过后只允许该次请求;忽略卡片、无效或缺失 Token、超时与取消均拒绝。Channel 模式的终端提示仍同时有效,由宿主采用最先到达的有效响应。项目 trust 与 MCP consent 只能在本地完成。
153
+
154
+ ## 角色与权限边界
155
+
156
+ - 外部 Agent 的 `owner` / `admin` 可重绑或解绑主机;只有唯一剩余的 `owner` 可按 Nia Teams 移除规则归档。重绑/解绑递增 `keyGeneration` 并使旧主机失效,归档也会撤销连接。
157
+ - 群聊成员可以调用 Agent 或忽略当前确认卡。批准 TaskBar 卡片的点击者必须同时是该外部 Agent 的有效成员(`owner` / `admin` / `member`);Nia Teams 校验后才签发 Token。同群但不是 Agent 成员的人不能批准。
158
+ - 主机独立验证 RS256 签名、issuer、audience、有效期、service 身份、人类确认、精确 card ID、工具名与 canonical argument digest。仅凭 `clickedBy.teamRole` 不构成批准证明。
159
+ - Agent 的 workload 身份字段 `sub`、`org:*`、`role:*` 不等于人类成员角色。本桥通过 Ed25519 challenge/lease 认证,不会把这些字段转换成本地 OS 权限。确认 Token 表示特定的人类已批准 service action。
160
+ - 本地执行仍受 Claude Code 权限系统与 sandbox 约束。配对不意味着任意 shell 授权,也不会改写本地工具权限或宿主配置。
161
+
162
+ ## CLI 与运行语义
163
+
164
+ ```text
165
+ nia-claude pair [--name <name>] [--server-url <origin>] [--config-dir <dir>] [--label <label>] [--timeout-ms <ms>]
166
+ nia-claude start [--cwd <dir>] [--config-dir <dir>] [--model <model>] [--claude-bin <path>] [--full-auto]
167
+ nia-claude status [--config-dir <dir>]
168
+ nia-claude mcp [--config-dir <dir>]
169
+ ```
170
+
171
+ - 服务 origin 优先级:`--server-url`、`NIA_TEAMS_URL`、`https://nia-teams.com`;后续命令使用凭证保存的 origin。
172
+ - 凭证目录优先级:`--config-dir`、`NIA_CLAUDE_CONFIG_DIR`、`~/.config/nia-teams-claude-code`。
173
+ - `start` 的 `--cwd` 默认为当前目录;`--model` 指定 Claude Code 模型;`--claude-bin`、`CLAUDE_BIN`、本机常见安装目录依次选择 CLI;`--full-auto` 开启免确认执行。
174
+ - 默认主机标签 `claude-code@<hostname>`;配对超时 600000 ms,每 2 秒轮询。
175
+ - 有界内存 FIFO 队列在短暂断线后重试回复,保留原 Nia session 与发布 UUID;进程崩溃后不持久保存。
176
+ - 后台 `start` 为各群聊持久化独立 SDK 会话;交互式 `mcp` Channel 中,多个 GroupChat 共享一个宿主/模型上下文。权限请求无群聊 ID,优先路由到最近触发且处于 executing 的群聊,否则路由到最近触发的已跟踪群聊。尚无群聊消息时,终端请求保持本地处理。需要隔离时使用独立宿主身份与会话。
177
+ - Channel 模式的 executing/waiting 每 30 秒续租。权限卡在本地 5 分钟超时。宿主协议不发送远程提示已结束通知,因此终端先批准后远端卡片可能保留至超时;宿主忽略已关闭请求的后续 verdict。
178
+ - 后台模式取消会中止 SDK 查询、清理该群聊输入队列和待确认卡。Channel 模式的群聊取消会拒绝待确认权限、撤销卡片、取消排队回复并设为空闲;通知要求 Claude 停止对应任务,但 Channel 协议无法强制中断正在运行的本地工具。
179
+ - Channel 模式中,stdin end/close、SIGINT/SIGTERM/SIGHUP 与 stdin watchdog 均触发尽力清理和有时限退出。MCP stdout 仅含 JSON-RPC,诊断写 stderr。`4409` 表示新主机接管,旧连接停止重连。
180
+
181
+ ## 排障与开发验证
182
+
183
+ 后台模式先检查 `/tmp/nia-claude.log`、`pgrep -af '[n]ia-claude.*start'`、本地 Claude 登录与 `--cwd` 权限。切换模式前停止旧连接;群聊会话状态保存在配对目录的 `threads.json`。
184
+
185
+ `npx @nia-teams/claude-code-plugin status` 失败通常与缺失/轮换凭证或错误 origin 有关,在本地重新配对并重启宿主。持续未连接时检查 `/mcp`、宿主 stderr/debug 日志、凭证目录与重复服务注册。缺少群聊回复时确认 Claude 是否只写了终端文字而未调用发送工具。Channel 通知被丢弃可能是未启用或组织策略限制;写入 transport 成功不代表宿主已消费消息。
186
+
187
+ ```sh
188
+ npm ci
189
+ npm run typecheck
190
+ npm run build
191
+ npm test
192
+ npm pack --dry-run
193
+ ```
194
+
195
+ 测试使用本地 HTTP/WebSocket 服务、Ed25519 持有证明、真实 RS256/JWKS 签名、MCP 内存客户端与 stdio 子进程,无需真实服务凭证。嵌入入口参见 [`examples/`](./examples/) 与 `dist/*.d.ts`。
196
+
197
+ ## 商标与许可证
198
+
199
+ Claude and Claude Code are trademarks of Anthropic, PBC. `@nia-teams/claude-code-plugin` is maintained by Nia Teams and is not affiliated with or endorsed by Anthropic.
200
+
201
+ [MIT](./LICENSE) © Nia Teams
@@ -0,0 +1,4 @@
1
+ #!/usr/bin/env node
2
+ import { main } from '../dist/cli.js';
3
+ try { await main(); }
4
+ catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
@@ -0,0 +1,5 @@
1
+ /** Client-owned product identity; PNG is shipped inline in standalone packages. */
2
+ export declare const clientBranding: {
3
+ clientName: string;
4
+ avatar: string;
5
+ };