nexum-code 0.18.7 → 0.20.1
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.
- package/README.md +14 -14
- package/dist/{app-aqWxJw2S.mjs → app-CYLTD0b3.mjs} +19994 -15221
- package/dist/{dispatch-DQ6ufFQt.mjs → dispatch-DnZRjRNm.mjs} +21929 -9483
- package/dist/{dispatch-ByfuGE0h.mjs → dispatch-cUxbpzTE.mjs} +1 -1
- package/dist/{markit-XGWU21rO.mjs → esm-C0toZ4e0.mjs} +19 -2344
- package/dist/main.mjs +1 -1
- package/dist/markdown-BwvhOvCA.mjs +25943 -0
- package/dist/markit-LwaDGgYt.mjs +2334 -0
- package/dist/{src-pqi1HIGh.mjs → src-C6YAs3fd.mjs} +1 -1
- package/dist/{src-BPh-7A8j.mjs → src-C8mW2wSe.mjs} +779 -276
- package/dist/{text-input-dialog-CAaXBGxG.mjs → text-input-dialog-BbyJmVbH.mjs} +1 -1
- package/dist/{text-input-dialog-BIhpfWk_.mjs → text-input-dialog-CAxwn6Ze.mjs} +930 -74
- package/docs/architecture.md +80 -0
- package/docs/configuration.md +204 -0
- package/docs/line.md +159 -0
- package/docs/mcp.md +141 -0
- package/docs/plugins.md +198 -0
- package/docs/sessions.md +78 -0
- package/docs/skills.md +76 -0
- package/package.json +9 -8
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Architecture
|
|
2
|
+
|
|
3
|
+
This guide focuses on the CLI/TUI subset of the monorepo. The repository also
|
|
4
|
+
contains server applications and a separate desktop product. Core capabilities
|
|
5
|
+
in `apps/nexum-code` must go through the SDK's public API.
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
apps/nexum-code terminal UI (TUI), CLI, commands
|
|
9
|
+
├── packages/node-sdk public session API over RPC
|
|
10
|
+
│ └── packages/agent-core engine: agent loop, tools, permissions, prompts, records
|
|
11
|
+
│ ├── packages/ltod LLM abstraction (providers, streaming, tokens)
|
|
12
|
+
│ ├── packages/jian execution environment (process, fs, env)
|
|
13
|
+
│ ├── packages/memory memo store (FTS5 + tags + vectors)
|
|
14
|
+
│ └── packages/knowledge local knowledge base
|
|
15
|
+
├── packages/config platform config, model catalog, i18n
|
|
16
|
+
└── packages/evals evaluation harness
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The SDK exposes the engine through an RPC contract so callers do not import
|
|
20
|
+
`agent-core` directly. The engine can run in-process or out-of-process behind
|
|
21
|
+
that contract.
|
|
22
|
+
|
|
23
|
+
The desktop is a separate product: Electron renderer → HTTP/WebSocket →
|
|
24
|
+
standalone Rust `aioncore` under `apps/nexum-desktop/aioncore`. Native Electron
|
|
25
|
+
IPC is reserved for OS capabilities; desktop business calls use the HTTP
|
|
26
|
+
bridge, not the TypeScript SDK or direct Rust crate access.
|
|
27
|
+
|
|
28
|
+
Document parsing, OCR, table reconstruction, extraction, validation, evidence
|
|
29
|
+
mapping and export belong in `packages/document-intelligence`. TUI, SDK,
|
|
30
|
+
server and desktop integrations call its typed APIs, job APIs or compiled
|
|
31
|
+
skill CLIs; this logic must not live in the TUI or desktop renderer.
|
|
32
|
+
|
|
33
|
+
## agent-core
|
|
34
|
+
|
|
35
|
+
| Area | Path | Role |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| Agent loop | `agent/index.ts` | turn lifecycle, tool dispatch, subagents |
|
|
38
|
+
| Tools | `tools/builtin/*` | 49 built-in tools across 15 groups |
|
|
39
|
+
| Permissions | `agent/permission/` | mode policy, rules, egress allowlist |
|
|
40
|
+
| Injection | `agent/injection/` | dynamic reminders (goal, permission mode, plan mode, user prefs, wolfpack, todo, working set, MCP guides) |
|
|
41
|
+
| Prompts | `profile/` | `default/system.md` template, conditional parts, self-asset map |
|
|
42
|
+
| Records | `agent/records/` | `wire.jsonl` persistence and replay |
|
|
43
|
+
| Compaction | `agent/compaction/` | summarisation and thresholds |
|
|
44
|
+
| Skills | `skill/` | scan, parse, registry |
|
|
45
|
+
| MCP | `mcp/` | config, stdio/HTTP clients, OAuth, tool naming |
|
|
46
|
+
|
|
47
|
+
## Prompt assembly
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
profile/default/system.md (nunjucks)
|
|
51
|
+
├─ static part → conditional sections (IS_MAIN, CAN_SPAWN, HAS_WRITE_EDIT, OS)
|
|
52
|
+
└─ dynamic part → cwd listing, AGENTS.md, skills, self-asset map, role additions
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
The two parts are separated so the static half stays cacheable. Mode changes do
|
|
56
|
+
not re-render the prompt; they are announced through the injection layer
|
|
57
|
+
instead.
|
|
58
|
+
|
|
59
|
+
## Event flow
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
user input → TUI controller → Session.prompt()
|
|
63
|
+
→ core RPC → agent turn → LLM stream + tool calls
|
|
64
|
+
→ records (wire.jsonl) + events
|
|
65
|
+
→ Session event emitter → TUI controller → render
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Permissions are evaluated inside the tool dispatch path, before execution.
|
|
69
|
+
Denials return a reason to the model rather than throwing.
|
|
70
|
+
|
|
71
|
+
## Testing
|
|
72
|
+
|
|
73
|
+
| Scope | Location |
|
|
74
|
+
|---|---|
|
|
75
|
+
| Engine, tools, prompts, sessions | `packages/*/test/` |
|
|
76
|
+
| TUI controllers, commands, rendering | `apps/nexum-code/test/` |
|
|
77
|
+
| Cross-package behaviour | root vitest projects |
|
|
78
|
+
|
|
79
|
+
`pnpm exec vitest run` runs every project; `pnpm run lint:ratchet` enforces a
|
|
80
|
+
warning baseline that may only go down.
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
# Configuration
|
|
2
|
+
|
|
3
|
+
Everything persistent lives under the Nexum home directory: `~/.nexum-code`
|
|
4
|
+
(override with `NEXUM_CODE_HOME`).
|
|
5
|
+
|
|
6
|
+
```
|
|
7
|
+
~/.nexum-code/
|
|
8
|
+
├── config.toml # providers, models, permissions, hooks, services
|
|
9
|
+
├── mcp.json # MCP servers (user level)
|
|
10
|
+
├── image-config.json # image-generation endpoint
|
|
11
|
+
├── skills/ # user skills
|
|
12
|
+
├── memory/ # memo store
|
|
13
|
+
├── knowledge/ # knowledge base
|
|
14
|
+
└── sessions/ # transcripts, bucketed by working directory
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
A project can add its own layer with `.nexum-code/` in the repository root
|
|
18
|
+
(`mcp.json`, `skills/`, `AGENTS.md`).
|
|
19
|
+
|
|
20
|
+
## config.toml
|
|
21
|
+
|
|
22
|
+
Parsed by `packages/agent-core/src/config/schema.ts`.
|
|
23
|
+
|
|
24
|
+
| Section | Purpose |
|
|
25
|
+
|---|---|
|
|
26
|
+
| `providers` | Named endpoints: `type`, `apiKey`, `baseUrl`, `defaultModel`, `oauth`, `env`, `customHeaders`, `sessionHeader` |
|
|
27
|
+
| `models` | Model aliases (see below) |
|
|
28
|
+
| `defaultProvider` / `defaultModel` | What a new session uses |
|
|
29
|
+
| `defaultPermissionMode` | `yolo` \| `manual` \| `auto` \| `ask` \| `bot` |
|
|
30
|
+
| `defaultThinking` / `thinking` | Thinking mode and effort |
|
|
31
|
+
| `planMode` / `defaultPlanMode` | Plan-mode defaults |
|
|
32
|
+
| `yolo` | Yolo-mode defaults |
|
|
33
|
+
| `permission` | `rules[]` (`decision` allow/deny/ask, `scope`, `pattern`, `reason`) and `egressAllowlist` |
|
|
34
|
+
| `hooks` | Shell hooks fired on session events |
|
|
35
|
+
| `services` | Search providers (google / duckduckgo / bing / sogou / baidu) |
|
|
36
|
+
| `loopControl` | `maxStepsPerTurn`, retry and compaction thresholds, `toolPortal` (see below) |
|
|
37
|
+
| `background` | Background task limits |
|
|
38
|
+
| `secrets` | Redaction rules (`plain` / `regex`, `obfuscate` / `replace`, optional regex `flags`) |
|
|
39
|
+
| `extraSkillDirs` | Additional skill roots |
|
|
40
|
+
| `mergeAllAvailableSkills` | Merge every discovered skill instead of the project-scoped set |
|
|
41
|
+
| `raw` | Escape hatch for keys the schema does not model |
|
|
42
|
+
|
|
43
|
+
A fresh session starts in `manual`. Read and search tools can run directly.
|
|
44
|
+
Commands and file changes use the approval policy. Explicit modes and
|
|
45
|
+
configured permission rules still apply.
|
|
46
|
+
|
|
47
|
+
### Provider types
|
|
48
|
+
|
|
49
|
+
`anthropic`, `openai`, `nexum`, `google-genai`, `openai_responses`, `vertexai`.
|
|
50
|
+
|
|
51
|
+
`baseUrl` is optional: the built-in type supplies the default endpoint, which is
|
|
52
|
+
what makes "any OpenAI-compatible endpoint" work.
|
|
53
|
+
|
|
54
|
+
`api_key` takes a single credential, or a pool:
|
|
55
|
+
|
|
56
|
+
```toml
|
|
57
|
+
[providers.relay]
|
|
58
|
+
type = "anthropic"
|
|
59
|
+
api_key = ["sk-a", "sk-b"]
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
A pool is key rotation: requests start at a session-affine key, and a
|
|
63
|
+
quota-style 429 rotates to the next usable key while the rejected one cools down
|
|
64
|
+
(30s). Only the rotation-capable types accept one — `anthropic`, `openai`,
|
|
65
|
+
`openai_responses`; every other type takes a single key and rejects an array at
|
|
66
|
+
load time. Blank entries are dropped, and an unusable pool falls back to the
|
|
67
|
+
provider's `env` entry like an unset key.
|
|
68
|
+
|
|
69
|
+
### Model aliases
|
|
70
|
+
|
|
71
|
+
A model is an alias, never a raw provider model string:
|
|
72
|
+
|
|
73
|
+
```toml
|
|
74
|
+
[models.my-model]
|
|
75
|
+
provider = "my-provider" # must match a key under [providers]
|
|
76
|
+
model = "vendor-model-id" # what the provider expects on the wire
|
|
77
|
+
maxContextSize = 200000
|
|
78
|
+
maxOutputSize = 16000
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Optional: `capabilities`, `displayName`, `reasoningKey`, `adaptiveThinking`,
|
|
82
|
+
`forceThinking`, `thinkingLevels`, `tokenizer`.
|
|
83
|
+
|
|
84
|
+
`tokenizer` selects the measurement used by local token estimates — compaction
|
|
85
|
+
watermarks and the context gauge:
|
|
86
|
+
|
|
87
|
+
```toml
|
|
88
|
+
[models.my-model]
|
|
89
|
+
tokenizer = "heuristic" # cl100k (default) | o200k | heuristic
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`cl100k` and `o200k` count with the matching OpenAI encoding; `heuristic` keeps
|
|
93
|
+
the character estimate (ASCII ~4 chars per token, other characters ~1 token).
|
|
94
|
+
Encoder counts are near-exact, not exact — Anthropic and Gemini tokenizers are
|
|
95
|
+
closed — and every estimate is re-anchored by the provider-reported usage at
|
|
96
|
+
each step end, so only local watermarks and the budget display depend on it.
|
|
97
|
+
|
|
98
|
+
Aliases are what `/model`, `--model`, subagent profiles and goal judging refer
|
|
99
|
+
to. Removing a provider orphans every alias that pointed at it — Nexum detaches
|
|
100
|
+
the model from a live session instead of ending the session when that happens.
|
|
101
|
+
|
|
102
|
+
### Loop control
|
|
103
|
+
|
|
104
|
+
`loop_control` holds the per-turn budget, retry and compaction knobs. One switch
|
|
105
|
+
changes the tool surface:
|
|
106
|
+
|
|
107
|
+
```toml
|
|
108
|
+
[loop_control]
|
|
109
|
+
tool_portal = "off"
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
The deferred-tool portal is on by default: low-frequency built-in groups (cron,
|
|
113
|
+
memory, knowledge, goal, image, make-skill, manage-plugin, inspect, debug) are
|
|
114
|
+
held behind a single discovery tool so their schemas stay off every request.
|
|
115
|
+
`tool_portal = "off"` restores the pre-portal behavior — every enabled tool is
|
|
116
|
+
declared up front.
|
|
117
|
+
|
|
118
|
+
#### Session token limit
|
|
119
|
+
|
|
120
|
+
```toml
|
|
121
|
+
[loop_control]
|
|
122
|
+
max_session_tokens = 100000000 # 0 or unset = no limit
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
A circuit breaker for unattended work (`/goal`, `/loop`, cron, wide subagent
|
|
126
|
+
fan-out). You normally do not edit it by hand: **`/budget`** sets it
|
|
127
|
+
interactively — `/budget` opens a list, `/budget 50m` sets it directly (`500k`,
|
|
128
|
+
`20m`, `1.5b`, `500万`, `1亿` all work), `/budget off` removes it. The change
|
|
129
|
+
applies to the running session at once (raising the limit un-pauses a stopped
|
|
130
|
+
session — no restart) and is saved here as the default for new sessions.
|
|
131
|
+
|
|
132
|
+
The unit is **tokens**, not money: a dollar limit needs a price from the model
|
|
133
|
+
catalog, and custom providers and self-hosted models have none, so it would
|
|
134
|
+
count them as free and never trip. A token count exists for every model.
|
|
135
|
+
|
|
136
|
+
Tokens are counted the way `/usage` shows them — input (cache reads included)
|
|
137
|
+
plus output, the same total `/goal` budgets use. Every agent step re-sends the
|
|
138
|
+
context, so a busy session moves tens of millions of tokens; the `/budget`
|
|
139
|
+
presets (10M – 1B) are sized for that. The count covers the whole session: the
|
|
140
|
+
main agent, every subagent (including ones still running), compaction and the
|
|
141
|
+
cache warmer. Once it reaches the limit, every turn ends before its next model
|
|
142
|
+
request — no wrap-up request either — and the cache warmer stops. The TUI shows
|
|
143
|
+
a warning that points at `/budget`, `-p` / stream-json exit non-zero
|
|
144
|
+
(stream-json uses exit code 4, like the step budget), an active goal is paused,
|
|
145
|
+
and LINE replies with the reason.
|
|
146
|
+
|
|
147
|
+
- The limit counts what this run of the session has used. Reopening (resume) or
|
|
148
|
+
starting a new session starts a fresh allowance; `/usage` keeps showing the
|
|
149
|
+
lifetime total, and shows this run's use against the limit while one is set.
|
|
150
|
+
- Side questions (`/btw`), exit memory extraction, knowledge-base text calls
|
|
151
|
+
and goal grading count too (under the session alias), but they are not
|
|
152
|
+
blocked by the limit — only turns are.
|
|
153
|
+
- Setting a limit below what this run already used pauses requests at once;
|
|
154
|
+
`/budget` says so when you do.
|
|
155
|
+
- While the limit is tripped, recurring cron / `/loop` jobs skip their fires
|
|
156
|
+
(a skipped fire would only open an empty turn, repeat the warning, and — on
|
|
157
|
+
an IM channel — repeat it in the chat); they run again at the next fire after
|
|
158
|
+
the limit is raised. A one-shot reminder is still delivered.
|
|
159
|
+
|
|
160
|
+
## Image generation
|
|
161
|
+
|
|
162
|
+
`~/.nexum-code/image-config.json`, written by `/config image`:
|
|
163
|
+
|
|
164
|
+
```json
|
|
165
|
+
{ "provider": "...", "url": "https://.../images/generations", "api_key": "...", "model": "..." }
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
`url` is the full endpoint, not a base URL. Placeholder values (empty,
|
|
169
|
+
`replace-with*`, `<...>`) count as unconfigured. The `image` skill and `/image`
|
|
170
|
+
read it through the `ImageGenerate` tool.
|
|
171
|
+
|
|
172
|
+
## Resolution order
|
|
173
|
+
|
|
174
|
+
1. CLI flag (`--model`, `--yolo`, `--auto`, `--plan`, `--permission-mode bot`)
|
|
175
|
+
2. `config.toml` defaults
|
|
176
|
+
3. Built-in defaults
|
|
177
|
+
|
|
178
|
+
`/config` writes `config.toml`; `/logout` removes a provider and clears any alias
|
|
179
|
+
that pointed at it.
|
|
180
|
+
|
|
181
|
+
## Optional dependencies
|
|
182
|
+
|
|
183
|
+
- `debugpy` — the Python debugging tools drive it over DAP; install it into the
|
|
184
|
+
interpreter the session uses (`python3 -m pip install debugpy`). Without it
|
|
185
|
+
the debug tools return that install command instead of a raw spawn error.
|
|
186
|
+
- `@ast-grep/napi` — bundled with the CLI and backing the AST search/edit
|
|
187
|
+
tools; a source checkout resolves it through the workspace install.
|
|
188
|
+
- `rg` (ripgrep) — backs `Grep`. It is looked up on `PATH`, then in
|
|
189
|
+
`~/.nexum-code/bin`; if neither has it, a pinned release is downloaded from
|
|
190
|
+
GitHub once. The download gives up if the server does not answer or the data
|
|
191
|
+
stops for 30 seconds, and a failed attempt is not repeated for two minutes (so
|
|
192
|
+
a blocked network costs one wait, not one per search). Where GitHub is slow or
|
|
193
|
+
unreachable, either install ripgrep with your package manager, put a static
|
|
194
|
+
`rg` in `~/.nexum-code/bin`, or set `NEXUM_RG_DOWNLOAD_BASE_URL` to a mirror
|
|
195
|
+
of `https://github.com/BurntSushi/ripgrep/releases/download/15.0.0` (same file
|
|
196
|
+
names). Archives are always checked against pinned SHA-256 digests, so a mirror
|
|
197
|
+
cannot supply different bytes.
|
|
198
|
+
|
|
199
|
+
## Verifying a configuration
|
|
200
|
+
|
|
201
|
+
- `/config` — pick a provider, writes and reloads in one step
|
|
202
|
+
- `/model` — lists aliases that resolve against a live provider
|
|
203
|
+
- `/status`, `/usage` — what the current session is actually using
|
|
204
|
+
- `nexum --version` — confirms which build is installed
|
package/docs/line.md
ADDED
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
# Line — 原生通道(飞书 + 微信)
|
|
2
|
+
|
|
3
|
+
用 `/line` 把 Nexum Code 连到 IM:配置向导 + 后台守护进程。两个平台均为**官方接口**,无需公网 IP:
|
|
4
|
+
- **飞书**:开放平台 WebSocket 长连接
|
|
5
|
+
- **微信**:官方 ilink 机器人网关(`getupdates` 长轮询 + `sendmessage` 下发,微信官方 bot 开放接口)
|
|
6
|
+
|
|
7
|
+
## 快速开始
|
|
8
|
+
|
|
9
|
+
1. 在 TUI 里运行 `/line` → 选择「配置飞书(向导)」或「配置微信(向导)」
|
|
10
|
+
2. 飞书:选**「跟着向导创建应用(推荐)」**——向导分步带你走完官方流程(创建应用 → 启用机器人 → 开通权限 → 长连接订阅 → 发布 → 粘贴凭证,约 3 分钟,无需公网 IP),每步都有直达链接与说明;微信:选**「扫码登录(推荐)」**——终端显示登录链接,手机微信打开确认即可,token 与白名单自动写入。
|
|
11
|
+
已有现成凭证 → 直接「手动输入」粘贴(微信的现成 token 获取见下文)。
|
|
12
|
+
3. 凭证实测校验通过后写入 `~/.nexum-code/line/config.json`(权限 0600)。
|
|
13
|
+
4. 选择「立即启动」→ 后台守护进程拉起,footer 状态段显示 `◆ Line: Lark` / `◆ Line: Wechat`;守护没跑时显示 `◆ Line: 未连接`。
|
|
14
|
+
5. 在 IM 里给机器人发消息,nexum 会在对应会话里处理并回复。
|
|
15
|
+
|
|
16
|
+
## 单通道约束
|
|
17
|
+
|
|
18
|
+
`/line` 一次只服务**一个**通道:配置飞书后,微信向导不可再选(反之亦然)。要切换平台:`/line` → **卸载**(停守护 + 清 `~/.nexum-code/line/`),再运行另一平台的向导。直接手改配置文件塞进两个平台会被守护进程拒绝启动(fail-fast,不会静默双跑)。切换后,旧平台的会话仍保留在 `/sessions` 里(独立命名空间,互不干扰),只是不再被新通道使用。
|
|
19
|
+
|
|
20
|
+
## TUI 与 CLI 命令
|
|
21
|
+
|
|
22
|
+
| 命令 | 作用 |
|
|
23
|
+
|---|---|
|
|
24
|
+
| `/line` | 向导 + 启动 / 停止 / 重启 / 卸载(TUI 内) |
|
|
25
|
+
| `nexum line` | 前台运行守护进程(调试用) |
|
|
26
|
+
| `nexum line start` / `stop` / `status` | 后台启停与状态查询 |
|
|
27
|
+
|
|
28
|
+
## 配置文件
|
|
29
|
+
|
|
30
|
+
`~/.nexum-code/line/config.json`(0600)。飞书选项名与飞书开放平台/业界惯用命名对齐,微信选项名与 ilink 网关字段对齐:
|
|
31
|
+
|
|
32
|
+
### 通用字段
|
|
33
|
+
|
|
34
|
+
| 字段 | 默认 | 说明 |
|
|
35
|
+
|---|---|---|
|
|
36
|
+
| `permissionMode` | `auto` | 会话权限模式(见下节),IM 默认 `auto` |
|
|
37
|
+
| `autoStart` | true | TUI 启动时自动拉起守护进程 |
|
|
38
|
+
| `workDir` | 守护启动目录 | 会话工作目录 |
|
|
39
|
+
|
|
40
|
+
### 飞书(`feishu`)
|
|
41
|
+
|
|
42
|
+
| 字段 | 默认 | 说明 |
|
|
43
|
+
|---|---|---|
|
|
44
|
+
| `app_id` / `app_secret` | 必填 | 飞书应用凭证 |
|
|
45
|
+
| `allow_from` | 空 = 允许所有人 | 用户 ID 白名单(逗号分隔)。**建议配置** |
|
|
46
|
+
| `allow_chat` | 空 = 允许所有群 | 群聊 ID 白名单(仅群聊生效) |
|
|
47
|
+
| `group_only` | false | 只响应群聊 |
|
|
48
|
+
| `require_mention` | true | 群聊必须 @机器人(`false` 表示群内消息全部响应) |
|
|
49
|
+
| `share_session_in_channel` | false | 会话按「群」共享(默认按「群 + 用户」隔离) |
|
|
50
|
+
| `reaction_emoji` | `OnIt` | 收到消息的回应表情;`none` 关闭 |
|
|
51
|
+
| `done_emoji` | 关 | 完成后的表情(如 `THUMBSUP`);`none` 关闭 |
|
|
52
|
+
| `domain` | `https://open.feishu.cn` | Lark 国际版填 `https://open.larksuite.com` |
|
|
53
|
+
|
|
54
|
+
### 微信(`weixin`)
|
|
55
|
+
|
|
56
|
+
| 字段 | 默认 | 说明 |
|
|
57
|
+
|---|---|---|
|
|
58
|
+
| `token` | 必填 | ilink bot Bearer token |
|
|
59
|
+
| `base_url` | `https://ilinkai.weixin.qq.com` | 网关根地址(运营商不一致时才改) |
|
|
60
|
+
| `allow_from` | 空 = 允许所有人 | ilink 用户 ID 白名单(形如 `xxx@im.wechat`)。**建议配置** |
|
|
61
|
+
| `route_tag` | 空 | 运营商要求的 `SKRouteTag` 请求头 |
|
|
62
|
+
| `long_poll_timeout_ms` | 35000 | 长轮询超时 |
|
|
63
|
+
| `dedup_window_seconds` | 300 | 去重窗口(ilink 可能因 ACK 延迟重发同一消息) |
|
|
64
|
+
| `cdn_base_url` | `https://novac2c.cdn.weixin.qq.com/c2c` | 媒体 CDN 根地址(仅网关换域名时改) |
|
|
65
|
+
|
|
66
|
+
**微信 token 获取**——扫码登录是主路径,全程在 `/line` 向导内完成,**无需安装任何其他工具**:
|
|
67
|
+
1. `/line` → 「配置微信(向导)」→ **「扫码登录(推荐)」**:向导向官方网关申请登录链接 → 你在手机微信中打开并确认 → token 自动写入配置,你的微信 ID 自动加入 `allow_from` 白名单
|
|
68
|
+
2. 已有现成 token(运营商提供)→ 「手动输入 token」粘贴
|
|
69
|
+
|
|
70
|
+
**首次激活**:token 有效但会话过期(errcode -14)时,启动守护进程后用允许的微信账号给机器人**发一条消息**即可完成会话关联(context_token 机制——回复必须携带对方消息里的 context_token)。
|
|
71
|
+
|
|
72
|
+
**微信能力边界**:支持文字、引用(`[引用: …]` 前缀)、语音转写文本、**图片 / 文件 / 语音 / 视频收发**(见「媒体收发」);回复按 3800 字符分块、代码围栏感知切分;typing「对方正在输入」指示自动开启/结束。
|
|
73
|
+
|
|
74
|
+
## 媒体收发
|
|
75
|
+
|
|
76
|
+
两个平台都支持**图片与文件双向传输**,模型能看到你发的图,也能把工作目录里的图/文件发回给你。
|
|
77
|
+
|
|
78
|
+
| 方向 | 飞书 | 微信 |
|
|
79
|
+
|---|---|---|
|
|
80
|
+
| 入站图片 | `image` 消息、富文本 `post` 内嵌图;同一次连发的多张图在 800 ms 内合并为一轮(**回复某条消息时会立即发送,不做批量**,以免丢掉引用文本) | `image_item`,CDN 下载 + AES-128-ECB 解密 |
|
|
81
|
+
| 入站文件 | `file` / `audio` / `media`(视频)以及富文本 `post` 的 `files[]` → 落盘后把路径交给模型 | `file_item` / `video_item` / 无转写的 `voice_item` → 同上 |
|
|
82
|
+
| 出站 | `image.create` / `file.create` 上传后按 `image` / `file` 消息发出 | `getuploadurl` → CDN 加密上传 → `sendmessage` 媒体 item(图片/文件/视频/**语音**) |
|
|
83
|
+
| 单张上限 | 入站图片 8 MiB;附件入站 32 MiB;出站 25 MiB | 同左(入站 CDN 单包 100 MiB 硬上限) |
|
|
84
|
+
| 大文件 | 下载走 `Range` 分块(绕过官方 SDK 在 ~2 MiB 处的截断),上限 512 MiB | 直连 CDN |
|
|
85
|
+
|
|
86
|
+
- **引用消息**:回复某条消息时会把被引用内容压成 `[引用: …]`(500 字截断)带进本轮;被引用消息里的图片(≤2 张)会一并取回,**文件只在引用者与被引用消息同一发送者时才取回**(防止群成员把别人的文件拉进自己的会话)。
|
|
87
|
+
- **入站附件落盘位置**:`~/.nexum-code/line/inbox/<会话键>/<时间戳>-<文件名>`(0600,不写进你的项目目录)。
|
|
88
|
+
- **图片如何进模型**:作为 `image_url` 内容分片直接进入本轮对话,无需模型再读文件;附件则以路径形式告知,模型自行用 `ReadMediaFile` / `Read` 打开。
|
|
89
|
+
- **出站工具**:模型侧工具 `line_send_media`(仅在 IM 会话可见)。只允许发送**工作目录内**的普通文件(realpath 校验,防目录穿越与符号链接逃逸),单文件 ≤ 25 MiB;`.png/.jpg/.gif/.webp/.bmp` 按图片发送,`.amr/.wav/.mp3/.m4a/.aac/.ogg/.oga/.opus/.silk/.flac` 按语音发送,其余按文件发送;也可显式传 `kind`(`image` / `file` / `audio`)。
|
|
90
|
+
- **语音出站(微信)**:网关只接受 **AMR-NB**(8 kHz / 单声道 / 12.2 kbps)。非 AMR 音频先用 **ffmpeg** 转码(走 stdin/stdout 管道,不落临时文件);本机没有 ffmpeg、或 ffmpeg 缺少 AMR-NB 编码器时**自动降级为文件消息**,并在工具回执里说明原因,不会让整轮失败。
|
|
91
|
+
- macOS:`brew install ffmpeg`(注意 Homebrew 官方构建**可能不含** `libopencore_amrnb`,可用 `ffmpeg -encoders | grep amr` 自检)。
|
|
92
|
+
- Ubuntu/Debian:`sudo apt install ffmpeg`。
|
|
93
|
+
- Windows:从 ffmpeg.org 下载带 `libopencore-amr` 的构建并加入 `PATH`(`ffmpeg.exe`)。
|
|
94
|
+
- 仅 **AMR-NB**(`#!AMR\n`)会直接发送;AMR-WB(`#!AMR-WB`)及其他格式一律先转码。
|
|
95
|
+
- 飞书侧语音统一按**文件**发送(语音气泡仅微信支持),回执会注明。
|
|
96
|
+
- **失败回执**:图片/附件下载失败会回一句「图片下载失败,请重新发送一次。」,不会静默吞掉。
|
|
97
|
+
|
|
98
|
+
## 在 IM 里可用的命令
|
|
99
|
+
|
|
100
|
+
直接在对话里发斜杠命令,由守护进程拦截执行,**不会进入模型**(不消耗 token):
|
|
101
|
+
|
|
102
|
+
| 命令 | 作用 |
|
|
103
|
+
|---|---|
|
|
104
|
+
| `/status` | 当前模型、权限/计划/群狼/RLM 模式、上下文占用与思考级别 |
|
|
105
|
+
| `/model <名称>` | 切换模型;不带参数显示当前模型 |
|
|
106
|
+
| `/compact` | 压缩上下文 |
|
|
107
|
+
| `/stop` | 停止**正在运行**的那一轮,并丢弃该聊天还在排队的消息(IM 版的 ESC;忙时也可用),回执「已停止当前任务。」;若 10 秒内停不下来(工具挂死),会关闭在线会话,下一条消息自动恢复同一会话 |
|
|
108
|
+
| `/cancel` | 停止并开启新会话(等价 `/stop` + `/new`,忙时也可用) |
|
|
109
|
+
| `/cron` | 查看本聊天的定时任务(含「静默/静音」标记与「上次失败」);`/cron add [--silent\|--mute] <分 时 日 月 周> <要做的事>` 新建;`/cron rm <id>` 删除 |
|
|
110
|
+
|
|
111
|
+
- `--silent`:触发时不发「⏰ 已触发」,只发结果;`--mute`:什么都不发(纯后台维护任务)。模型侧 `CronCreate` 对应参数 `silent` / `mute`。
|
|
112
|
+
- 任务失败会在 `/cron` 列表里留一行「上次失败:…」,下次成功自动清除。
|
|
113
|
+
| `/new` | 丢弃当前会话,下条消息开新会话 |
|
|
114
|
+
| `/help` | 命令列表(含自定义命令) |
|
|
115
|
+
| `/自定义` | 你自己在配置里定义的命令(`prompt` 型或 `exec` 型) |
|
|
116
|
+
|
|
117
|
+
- 有任务正在处理时,`/model`、`/compact`、`/new` 会回复「请等这一轮结束(回复 /stop 可中止)」,避免与运行中的回合争用;`/stop` 本身**不受忙限制**。
|
|
118
|
+
- 消息排在别人后面时,会立刻回一条 `收到,前面还有 N 条在处理中。回复 /stop 可中止当前任务。`——不再静默排队。
|
|
119
|
+
- **定时任务现在能回到聊天**:`cron.fired` 在会话里触发后,守护进程会先发一行 `⏰ 定时任务已触发:…`,等这一轮跑完再把最终内容发到该聊天。投递靠记下的聊天目标:飞书的「会话 → 群聊」对应关系存在 `line/feishu/chats.json`,微信用本机保存的 context_token(`line/weixin/context_tokens.json`)找回对方。
|
|
120
|
+
- **守护进程重启后定时任务照常触发**:启动时会自动恢复带定时任务的聊天会话(即使改过工作目录也能找到),不必等你先发消息;停机期间错过的触发会在恢复后补发一次(重复任务会注明合并了几次)。飞书可直接推送;微信用重启前保存的 context_token 推送,若微信判定该 token 已失效,需要你在微信里再发一条消息才能恢复推送(日志会提示)。触发时若正有你的回合在跑,结果并入那一轮回复,不会重复推送。
|
|
121
|
+
- `/status` 末尾会带上启动时的语音能力探测结果(ffmpeg / AMR-NB 编码器是否可用),缺编码器意味着语音会降级成文件。
|
|
122
|
+
- **自定义命令**:配置项的 `commands` 数组里定义,`prompt` 型会把模板(`{args}` 会被替换,无占位符则把参数附在末尾)作为一轮输入发给模型;`exec` 型在守护进程里执行 shell(macOS/Linux 为 `/bin/sh -c`,Windows 为 `%ComSpec% /d /s /c`;30 s 超时、输出截断 8 KiB、参数通过 `LINE_ARGS` 环境变量传递、`work_dir` 必须位于工作目录内)。Windows 上出于命令注入安全考虑**不支持 `{args}` 占位符**,请在脚本里读 `%LINE_ARGS%`。命令名不能与内置命令重名、不能重复。
|
|
123
|
+
- **未识别的命令照常发给模型**;需要界面交互的命令(`/theme`、`/line` 向导、无参 `/model` 选择器、`/sessions`)会提示「需要桌面端」。
|
|
124
|
+
|
|
125
|
+
## 模型如何感知当前通道
|
|
126
|
+
|
|
127
|
+
每次建立/恢复会话时,守护进程会向该会话注入一段渠道说明(运行时 system prompt,不进入对话正文):当前是 Lark 还是 WeChat、能收什么、能发什么、**没有桌面截图能力**、超长回复会被分块。因此模型不会再说「我给你截图」,也不会声称看到了你并未发送的附件。
|
|
128
|
+
|
|
129
|
+
## 运行边界
|
|
130
|
+
|
|
131
|
+
- **单轮默认上限 60 分钟**:可通过 `turnTimeoutMinutes` 配置;超过即取消该轮并回复「本轮执行超时」,避免某次卡死的请求把整个会话队列永久占住。
|
|
132
|
+
- **`/new` 互斥**:重置进行中到达的消息会收到「会话正在重置,请稍后重发」;已有回合会先跑完再删存储。
|
|
133
|
+
- **关停**:优雅关停时先排空各会话队列(最多 60 秒),再预留 10 秒关闭传输层与会话;外部停止控制器在 71 秒后才会强制终止仍未退出的进程。Windows 的 `line stop` 例外见下文。
|
|
134
|
+
|
|
135
|
+
## 权限与安全
|
|
136
|
+
|
|
137
|
+
- `permissionMode: auto`(**默认**)= 策略层在 deny 规则之后全量放行,且不产生任何交互面(不弹提问、不做计划评审)——最适合 IM。
|
|
138
|
+
- `permissionMode: yolo` = 同样全自动,但会保留计划评审(ExitPlanMode)这一交互路径,IM 下不推荐。
|
|
139
|
+
- `permissionMode: dontAsk` = 不可逆操作(发布、推送、删除、敏感文件等)一律拒绝(决定记入审计;bot 不产生交互审批,也不排队等审);可逆操作仍会自动执行(bot 模式)。
|
|
140
|
+
- 三种模式都**不会**绕过 `deny` 规则;旧配置里显式写下的值保持原样,不会被默认值改写。
|
|
141
|
+
- 飞书群聊 @ 过滤是 **fail-closed**:机器人身份获取失败时宁可不响应,也不会抢答所有群消息。
|
|
142
|
+
- 微信 `allow_from` 未配置时任何私聊用户都能触发你的模型计费——**建议始终配置白名单**(ilink 用户 ID 形如 `xxx@im.wechat`)。
|
|
143
|
+
- Secret/token 以 0600 权限落盘;日志不含凭证。
|
|
144
|
+
- 远程会话与本地 TUI 会话互相独立,可在 `/sessions` 中查看(`source: line`)。
|
|
145
|
+
|
|
146
|
+
## 守护进程
|
|
147
|
+
|
|
148
|
+
- 独立进程:TUI 退出不影响通道;pidfile `~/.nexum-code/line/daemon.pid`(防双开 + 陈旧清理)。
|
|
149
|
+
- 日志:`~/.nexum-code/line/daemon.log`(超 5MB 轮转为 `daemon.log.1`)。
|
|
150
|
+
- 微信状态:`~/.nexum-code/line/weixin/`(长轮询游标 + context_token 缓存,均 0600,勿手动泄露)。
|
|
151
|
+
- `autoStart: true` 时随 TUI 启动自动拉起;崩溃后下次启动自动恢复。
|
|
152
|
+
- macOS/Linux:`line stop` 发送 SIGTERM,守护进程最多等待进行中的回合 60 秒,再用最多 10 秒清理;71 秒后外部停止控制器才会强制终止。
|
|
153
|
+
- Windows:Node 的 `process.kill(pid, 'SIGTERM')` 会直接终止目标,因此 `line stop` 是强制停止,无法保证排空或回复。需要优雅关停时,在前台运行 `nexum line run`,通过终端 Ctrl+C 触发上述等待与清理流程。参见 [Node 信号说明](https://nodejs.org/api/process.html#signal-events)。
|
|
154
|
+
|
|
155
|
+
## 通道归属
|
|
156
|
+
|
|
157
|
+
- `/line` 是 Nexum 内置的原生远程通道:**飞书(Lark)与微信(WeChat)二选一**,配置向导与守护进程全部内置,不依赖第三方桥接工具。
|
|
158
|
+
- 兼容通道 `/cc` 与 cc-connect 继续保留,已有配置和使用方式仍然可用;`/line` 的原生通道向导不替代或移除它们。
|
|
159
|
+
- 已配置的通道会话在 `/sessions` 里标记 `line-feishu` / `line-weixin`,由通道管理(不可在 TUI 中删除,避免与守护进程争用)。
|
package/docs/mcp.md
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# MCP Servers
|
|
2
|
+
|
|
3
|
+
Model Context Protocol servers extend the tool set with external processes or
|
|
4
|
+
HTTP endpoints. They are opt-in per session and configured in files, not flags.
|
|
5
|
+
|
|
6
|
+
## Configuration files
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
~/.nexum-code/mcp.json # user level
|
|
10
|
+
<project>/.nexum-code/mcp.json # project level
|
|
11
|
+
<parent>/.nexum-code/mcp.json # walked up from cwd, root → shallow
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
On a name collision the file **nearest the working directory** wins: the project
|
|
15
|
+
file beats any parent, and a nearer parent beats a shallower one. Discovery
|
|
16
|
+
logic: `packages/agent-core/src/mcp/config-loader.ts`.
|
|
17
|
+
|
|
18
|
+
## Shape
|
|
19
|
+
|
|
20
|
+
```json
|
|
21
|
+
{
|
|
22
|
+
"mcpServers": {
|
|
23
|
+
"my-server": {
|
|
24
|
+
"command": "npx",
|
|
25
|
+
"args": ["-y", "some-mcp-server"],
|
|
26
|
+
"env": { "TOKEN": "..." }
|
|
27
|
+
},
|
|
28
|
+
"remote": {
|
|
29
|
+
"url": "https://example.test/mcp",
|
|
30
|
+
"headers": { "Authorization": "Bearer ..." }
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
- `command` + `args` → stdio transport (`client-stdio.ts`)
|
|
37
|
+
- `url` → HTTP transport (`client-http.ts`)
|
|
38
|
+
- OAuth flows live under `packages/agent-core/src/mcp/oauth/`.
|
|
39
|
+
|
|
40
|
+
## How tools surface
|
|
41
|
+
|
|
42
|
+
MCP tool schemas are **not** in the request by default. The agent must call
|
|
43
|
+
`DiscoverMcpTools` first:
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
DiscoverMcpTools({}) # server overview
|
|
47
|
+
DiscoverMcpTools({ server: "linear" }) # one server's tools
|
|
48
|
+
DiscoverMcpTools({ tools: ["mcp__linear__create_issue"] }) # enable for this session
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Enabled tools appear from the next step on, named
|
|
52
|
+
`mcp__<server>__<tool>` (`mcp/tool-naming.ts`). `list`/`info`-style reads are
|
|
53
|
+
free; mutating MCP tools go through the normal permission policy.
|
|
54
|
+
|
|
55
|
+
## Managing from the TUI
|
|
56
|
+
|
|
57
|
+
- `/mcp` — list servers and their connection state
|
|
58
|
+
- A connected row shows the server's **own reported version** (`v1.13.0`) next to
|
|
59
|
+
the tool count. `chrome-devtools-mcp@latest` only says what was asked for; the
|
|
60
|
+
handshake is what tells you what resolved.
|
|
61
|
+
- Connection failures are reported per server and never block startup
|
|
62
|
+
|
|
63
|
+
## Built-in recommendations
|
|
64
|
+
|
|
65
|
+
`/mcp` offers two servers you can install with Enter: **Chrome DevTools**
|
|
66
|
+
(`npx chrome-devtools-mcp@latest`) and **NexumLife** (decision memory). The
|
|
67
|
+
entry written to `~/.nexum-code/mcp.json` is a normal entry — you can edit it by
|
|
68
|
+
hand afterwards; the panel only reads it back to detect drift.
|
|
69
|
+
|
|
70
|
+
The Chrome DevTools launch args are chosen, not arbitrary:
|
|
71
|
+
|
|
72
|
+
| Flag | Why |
|
|
73
|
+
|---|---|
|
|
74
|
+
| `--no-usage-statistics`, `--no-performance-crux` | no telemetry; trace URLs never leave the machine |
|
|
75
|
+
| `--redact-network-headers` | response/request headers are redacted before the model sees them |
|
|
76
|
+
| `--no-file-navigations` | `file:` navigation + `take_snapshot` would bypass the workspace boundary |
|
|
77
|
+
| `--screenshot-format=jpeg --screenshot-quality=85 --screenshot-max-width=1600` | keeps screenshots from dominating the context |
|
|
78
|
+
| `--category-network-mocks` | `mock_network` / `remove_network_mock` — testing error and empty states |
|
|
79
|
+
| `--memory-debugging` | heap-analysis tools; `take_heapsnapshot` alone returns an unreadable blob |
|
|
80
|
+
|
|
81
|
+
Tool schemas never enter the request (see above), so a wider tool surface costs
|
|
82
|
+
nothing per turn.
|
|
83
|
+
|
|
84
|
+
### Authentication (`a`)
|
|
85
|
+
|
|
86
|
+
An HTTP server that answers 401 (and has no `bearerTokenEnvVar` / `headers`
|
|
87
|
+
configured) lands in **needs-auth**. Press `a` on that row: nexum-code runs the
|
|
88
|
+
OAuth discovery (RFC 9728 / RFC 8414 / RFC 7591), opens the authorization page in
|
|
89
|
+
your browser, and reconnects by itself once the callback lands. The flow keeps
|
|
90
|
+
running in the background for up to 15 minutes — the panel stays usable and only
|
|
91
|
+
reports where to look.
|
|
92
|
+
|
|
93
|
+
The agent has the same capability through a synthetic
|
|
94
|
+
`mcp__<server>__authenticate` tool, so this works whether you start it or it does.
|
|
95
|
+
|
|
96
|
+
stdio servers cannot use this path: they authenticate through their own command
|
|
97
|
+
or env. If a server uses a static bearer token, set `bearerTokenEnvVar` in
|
|
98
|
+
`mcp.json` and nexum-code will report the missing variable when it is unset.
|
|
99
|
+
|
|
100
|
+
### Launch options (`o`)
|
|
101
|
+
|
|
102
|
+
On an installed Chrome DevTools row, `o` opens the launch-option menu: headless,
|
|
103
|
+
isolated profile, fixed viewport, Chrome channel and "connect to a running
|
|
104
|
+
Chrome". The values are written as launch args into `mcp.json` — nothing is
|
|
105
|
+
stored anywhere else — and only 「Save and restart」 writes, because each saved
|
|
106
|
+
change relaunches Chrome. Esc discards.
|
|
107
|
+
|
|
108
|
+
`auto-connect` drives a Chrome you started yourself (144+, remote debugging on
|
|
109
|
+
from `chrome://inspect`); the server then does not launch the browser, so headless
|
|
110
|
+
and isolated are refused rather than saved as inert switches.
|
|
111
|
+
|
|
112
|
+
### Upstream skills
|
|
113
|
+
|
|
114
|
+
The `chrome-devtools-mcp` package ships seven official Agent-Skills (a11y,
|
|
115
|
+
cookie and memory-leak debugging, LCP optimization, troubleshooting, CLI, and the
|
|
116
|
+
general Chrome DevTools playbook). The same submenu installs them into
|
|
117
|
+
`~/.nexum-code/skills/` and keeps a manifest of what it put there, so removal and
|
|
118
|
+
updates only ever touch its own directories — a same-named skill of yours is
|
|
119
|
+
skipped, never overwritten. Skills load when a session starts, so restart
|
|
120
|
+
(`/new`) after installing.
|
|
121
|
+
|
|
122
|
+
### Updating an existing install
|
|
123
|
+
|
|
124
|
+
Recommendations change; an entry keeps the args it was installed with. When the
|
|
125
|
+
panel sees the installed entry missing recommended flags, the recommendation row
|
|
126
|
+
reads **"N recommended flags missing — Enter to update"**. Enter asks for
|
|
127
|
+
confirmation (custom args and `env` are replaced), rewrites the entry and
|
|
128
|
+
reconnects the server, so the new flags apply immediately in that session.
|
|
129
|
+
|
|
130
|
+
Entries declared by a project `.nexum-code/mcp.json` or provided by a plugin are
|
|
131
|
+
refused — rewriting them would be undone on the next start. Update those at the
|
|
132
|
+
source.
|
|
133
|
+
|
|
134
|
+
## Gotchas
|
|
135
|
+
|
|
136
|
+
- A server that fails to start does not remove its siblings; only its tools are
|
|
137
|
+
missing.
|
|
138
|
+
- Tools disabled with `DiscoverMcpTools` stay out of the request until enabled
|
|
139
|
+
again in the same session.
|
|
140
|
+
- `mcp.json` is project-scoped configuration; committing it shares the server
|
|
141
|
+
definition (and any literal secrets) with everyone who checks out the repo.
|