@waq666/pneuma 0.7.0 → 0.7.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.
Files changed (41) hide show
  1. package/README.md +206 -145
  2. package/lib/app/App.d.ts +3 -1
  3. package/lib/app/App.js +324 -172
  4. package/lib/app/App.js.nv-backup +1650 -0
  5. package/lib/app/ChatView.d.ts +40 -9
  6. package/lib/app/ChatView.js +150 -38
  7. package/lib/app/StatusBar.js +21 -92
  8. package/lib/app/TimelineRail.d.ts +22 -0
  9. package/lib/app/TimelineRail.js +160 -0
  10. package/lib/app/TimelineRail.js.negbak +98 -0
  11. package/lib/app/TimelineRail.js.nv-backup +160 -0
  12. package/lib/app/ToolCard.d.ts +7 -1
  13. package/lib/app/ToolCard.js +30 -6
  14. package/lib/app/ToolCard.js.nv-backup +64 -0
  15. package/lib/app/TranscriptOverlay.d.ts +23 -8
  16. package/lib/app/TranscriptOverlay.js +29 -10
  17. package/lib/app/TranscriptViewport.d.ts +78 -0
  18. package/lib/app/TranscriptViewport.js +218 -0
  19. package/lib/app/Welcome.js +13 -8
  20. package/lib/app/click.d.ts +15 -2
  21. package/lib/app/click.js +20 -6
  22. package/lib/app/keymap.d.ts +56 -0
  23. package/lib/app/keymap.js +56 -0
  24. package/lib/app/mouse.d.ts +33 -0
  25. package/lib/app/mouse.js +35 -0
  26. package/lib/app/pointer.d.ts +16 -0
  27. package/lib/app/pointer.js +60 -0
  28. package/lib/app/scroll-model.d.ts +240 -0
  29. package/lib/app/scroll-model.js +347 -0
  30. package/lib/app/snapshot-subscribe.d.ts +34 -0
  31. package/lib/app/snapshot-subscribe.js +110 -0
  32. package/lib/app/theme.d.ts +29 -1
  33. package/lib/app/theme.js +46 -1
  34. package/lib/app/ticker.d.ts +7 -0
  35. package/lib/app/ticker.js +53 -0
  36. package/lib/core/llm.d.ts +11 -0
  37. package/lib/core/llm.js +19 -2
  38. package/lib/plugins/subagent.js +36 -2
  39. package/lib/plugins/tool-search.js +11 -2
  40. package/lib/plugins/tool-search.js.nv-backup +434 -0
  41. package/package.json +1 -1
package/README.md CHANGED
@@ -1,145 +1,206 @@
1
- # Pneuma — 独立终端 AI harness
2
-
3
- **全自研**的终端 AI 编程助手:自写 ReAct loop + 会话落盘 + 工具栈 + 审批,UI 用 ink(React for CLI),另有 Electron 桌面端;插件装配基于开源 cordis 上下文内核。
4
-
5
- ## 有什么
6
-
7
- - **一颗内核,三种前端**:终端 TUI、Electron 桌面端(默认已是插件化界面壳)、**手机浏览器遥控页**——局域网扫码配对,人在外面也能批卡、看进度、发消息(PWA + Web Push + Webhook)。
8
- - **模型自由**:多端点 / 多模型随意切;上下文窗口、思考档位、图片 / 视频模态逐模型配置并可就地实测。输入框底栏两颗 chip 直接换模型与思考强度。
9
- - **智能体协作**:子智能体、智能体团队(并行队友 + 收件箱 + 汇报)、任务清单、计划交付、跨轮目标续跑。
10
- - **长期记忆**:跨会话事实分「全局 / 用户偏好 / 工作区」三格,当轮生效,可评估、可整理。
11
- - **插件化**:每个服务一个 cordis 插件;官方 17 个可开关插件(见下)+ 单文件 ESM 第三方插件;桌面界面壳本身也是插件架构(带 SDK)。
12
- - **安全默认**:写 / 执行一律过审批卡(一次授权一次生效);沙箱策略围栏、危险命令灾难地板、权限三档 × 审阅者正交轴。
13
- - **长会话省 token**:旧工具结果按轮微压缩、历史图片按预算卸载、压缩前回插读过的文件、端点侧显式缓存断点。
14
-
15
- ## 安装
16
-
17
- **桌面端**(自带运行时,无需装 Node):到 [Releases](https://github.com/waq05/pneuma/releases) 下载
18
- 安装版 `pneuma-setup-x.y.z.exe`(可选安装目录)或免安装单文件 `pneuma-portable-x.y.z.exe`。
19
-
20
- **CLI**(`numa` 命令,需要 Node.js ≥ 22.19):
21
-
22
- ```sh
23
- npm i -g @waq666/pneuma # 或免安装:npx @waq666/pneuma
24
- numa # 独立启动(新会话)
25
- ```
26
-
27
- **从源码跑**:
28
-
29
- ```sh
30
- git clone https://github.com/waq05/pneuma
31
- cd pneuma && pnpm install && pnpm build
32
- npm i -g file:. # 全局 numa 命令指向本地构建
33
- ```
34
-
35
- `numa --resume` 恢复上次会话;`numa --resume <会话jsonl路径>` 恢复指定会话。
36
-
37
- ## 交互
38
-
39
- | 按键 / 命令 | 作用 |
40
- | --- | --- |
41
- | 直接输入 + Enter | 发送消息 |
42
- | 输入 `/` 后 | 输入框上方弹出候选面板:命令阶段列命令,`/model ` 后列**可用模型**(↑↓ 选择、Tab 补全、Esc 关闭) |
43
- | ↑ / ↓(空输入时) | 翻输入历史 |
44
- | Ctrl+C | 一次:打断当前回合;2 秒内两次:退出 |
45
- | Ctrl+T | 展开/折叠思考(reasoning) |
46
- | `/new` | 新建会话 |
47
- | `/resume` | 恢复历史会话(↑↓ 选择,Enter 确认,Esc 取消) |
48
- | `/compact` | 手动压缩上下文(自动阈值:估算 tokens > 80% × 模型上下文窗口) |
49
- | `/model [端点/]模型名` | 切换模型(下一次请求生效;候选来自配置里的全部 provider/model) |
50
- | 桌面端 Ctrl+V / 拖文件 | 把图片贴进输入框,随这条消息一起发出(模型没勾「照片」会被拒绝,见 §配置) |
51
- | 桌面端双击待发贴图 | 全屏预览大图(点任意处或 Esc 关闭);贴图在会话切换后各回各的,不会串到别的会话 |
52
- | `/help` `/exit` | 帮助 / 退出 |
53
-
54
- 面板打开时按 Enter 会采用当前选中项;命令名还支持**唯一前缀自动展开**(输入 `/ne` 按 Enter 即执行 `/new`)。
55
-
56
- 工具授权卡出现时:`y` 允许一次,`n`(或 Esc)拒绝。卡只弹在发起它的那个会话里——后台会话的卡不串到当前视图,切回去(状态点会亮)再答。
57
-
58
- ## 工具集(6 件)
59
-
60
- `bash`(PowerShell)、`read`、`write`、`edit`(唯一匹配替换)、`glob`、`grep`。
61
- 读类工具自动放行;**写/执行类必须过审批卡**(无持久授权,一次授权一次生效)。
62
-
63
- ## 配置
64
-
65
- Pneuma 只读**自己的**配置文件(`~/.dsc/`):
66
-
67
- - **`~/.dsc/config.yaml`**(主配置):`default`(默认 provider/model)+ `providers`
68
- (`displayName` / `baseURL` / `apiKeyEnv` / `models` 列表;可选 `api` 选线上协议适配器,
69
- 缺省 `openai-compat` 风格的 `openai-completions`,装了提供别的协议的插件后可换)。
70
- - **模型可选字段**(不写就用默认,设置界面「模型」分区每个模型一行可直接改):
71
-
72
- ```yaml
73
- models:
74
- - id: hy3-a
75
- contextWindow: 200000 # 上下文窗口(用于压缩阈值与侧栏显示)
76
- maxTokens: 32000 # 单次输出上限
77
- thinkingLevels: [off, low, max] # 这个模型支持哪几档思考(默认四档 off/low/high/max)
78
- thinkingParam: reasoning-effort # 档位发哪个字段:thinking / reasoning-effort / none
79
- effortMap: { low: minimal, max: ultra_max } # 各档发给端点的线上值(写 null = 不发字段)
80
- modalities: [text, image] # 能收什么输入:text / image / video
81
- ```
82
-
83
- `thinkingParam` 默认 `thinking`(只有开关、无档位字段的协议),此时低/高/最大都发 `thinking: enabled`;
84
- 网关按档位取值的(发 `reasoning_effort`)要显式写成 `reasoning-effort`,界面上的思考档位才会真的生效。
85
- `modalities` 没写 `image` 的模型,界面上贴图会被直接拒绝。
86
- - **key 来源顺序**:`apiKeyEnv` 指向的环境变量 → `~/.dsc/credentials.yaml`。代码绝不打印 key。
87
- - **`~/.dsc/config.json`**(可选轻量覆盖):`{ "provider": "...", "model": "...", "temperature": 0.7 }`。
88
-
89
- ```sh
90
- numa config show # 查看当前生效的端点/模型/key 来源(不打印 key)
91
- ```
92
-
93
- - **会话落盘**:`~/.dsc/sessions/<cwd 压缩名>/<uuid>.jsonl`(append-only,重放恢复);
94
- `~/.dsc/.last-session` 是 `--resume` 无参时的指针。
95
-
96
- ## 架构
97
-
98
- ```
99
- bin/dsc.js 启动器(零依赖):--resume / config 子命令 → spawn node lib/boot.js
100
- src/boot.ts 进程入口:读配置 → createKernel()(cordis 装配)→ 装 UI 插件
101
- src/tools/config-cli.ts numa config 命令行工具
102
- src/core/ 自研引擎(零 UI 依赖)
103
- config.ts 读 ~/.dsc/config.yaml + key 来源链(env → 凭据文件)
104
- llm.ts OpenAI chat-completions 流式客户端(SSE/reasoning/tool_calls/usage/重试)
105
- session.ts JSONL 会话(append-only + 重放恢复)
106
- loop.ts MiniAgent ReAct 循环(turn → stream → 审批 → 工具 → 定稿)
107
- tools/ bash/read/write/edit/glob/grep 注册表
108
- approval.ts 写/执行类挂起等 y/n
109
- compact.ts 保头折尾摘要压缩
110
- src/adapter/ core 事件 → 快照投影(transcript 折叠 + core-runtime)
111
- src/contract.ts UI ⇄ 运行时 的中性契约(DscRuntime)
112
- src/host/kernel.ts 内核装配顺序 + 三档插件清单(运行内核 / 官方可开关 / 自定义)
113
- src/plugins/ 每个服务一个 cordis 插件(含官方可开关插件,见下文清单)
114
- src/app/ ink UI(App/ChatView/Composer/ToolCard/ApprovalCard/SessionPicker/StatusBar)
115
- desktop/ Electron 桌面端:主进程 + 独立运行时子进程;界面默认加载壳产物,可回退旧渲染层
116
- ui-shell/ 桌面与手机共用的界面壳(插件化:布局 + 基元 + 官方界面插件;产物落 lib/ui/assets)
117
- scripts/composer-test.mjs 候选面板/输入行的确定性测试(node scripts/composer-test.mjs,16 项断言)
118
- ```
119
-
120
- **模式(Agent 预设)**:一根独立的旋钮,决定模型是谁、手上有什么、被叮嘱了什么(提示词 + 工具目录)。出厂四个——标准 / 极简 / 创造 / PTC,自己加的模式就是 `~/.dsc/presets/<名字>.md` 一个文件,设置页可图形编辑,输入框下方那颗旋钮或 `/preset <名字>` 切换。模式**只做减法**(工具白名单取子集、提示段只能摘掉四段),任何模式都放宽不了安全。详见 [docs/presets.md](docs/presets.md)。
121
-
122
- 官方可开关插件共 **17 个**(默认开:网页搜索、审批灾难地板、大输出溢出、会话全文检索、沙箱、文件更改预览;默认关:子智能体、智能体团队、电脑操作、生命周期钩子、MCP 客户端、工具渐进披露、定时任务、LSP 代码智能、浏览器自动化、侧栏浏览器控制、自我改进等),在插件中心里手动开关;长期记忆是默认开的内核插件。完整清单与各自干什么见 [docs/development.md](docs/development.md) 第 4 节。
123
-
124
- ## 已知限制
125
-
126
- - 沙箱是策略围栏(默认开的 sandbox 插件:可写根白名单、受保护路径、命令前缀策略、一次性升权),拦得住 Pneuma 自己发起的工具调用,**拦不住命令内部的任意写**——那要选容器后端;最终兜底仍是审批卡。
127
- - 插件能加工具、命令、事件监听、设置分区和技能来源,但拿不到 DOM:界面扩展只接受可 JSON 序列化的控件声明。
128
- - Windows 中文输入法可能拦截审批卡的 y/n 键(输入法切英文即可)。
129
- - **电脑控制**(无障碍元素级点击 / 拖拽 / 截图)目前仅 Windows,且没接沙箱——动作按危险分级审计,最终仍过审批卡。
130
- - 跨进程的路由状态(当前模型/思考强度)不落盘,重启宿主后回到配置默认值。
131
-
132
- ## 插件开发
133
-
134
- 外部插件 = 单个 ESM `.js` 文件放进 `~/.dsc/plugins/`,可注册工具、命令、监听事件,
135
- 桌面端「插件」页可视化管理。完整 API 与开发规范见 **[docs/plugin-development.md](docs/plugin-development.md)**;可运行示例见 `examples/plugins/ping.js`。
136
-
137
- ## 文档
138
-
139
- | 文档 | 讲什么 |
140
- | --- | --- |
141
- | [docs/development.md](docs/development.md) | 开发手册:运行时结构、三条启动链路、进程间协议、`~/.dsc` 数据面、扩展点清单、自检与打包、代码约定、排错与关键数值 |
142
- | [docs/development-log.md](docs/development-log.md) | 开发记录:各阶段引入了什么、决策台账、真 bug 台账、还欠什么 |
143
- | [docs/plugin-development.md](docs/plugin-development.md) | 插件 API 与开发规范 |
144
- | [docs/presets.md](docs/presets.md) | **模式(Agent 预设)**:模式文件怎么写、出厂四个各是什么、可去掉哪些提示段、四条硬规矩 |
145
- | [docs/ui-design.md](docs/ui-design.md) | 界面开发规范:设计原则、令牌体系、原语层、布局与反馈、键盘与动效、主题引擎对照 |
1
+ <p align="center">
2
+ <img src="docs/assets/readme/banner.png" width="560" alt="Pneuma — 独立终端 AI harness">
3
+ </p>
4
+
5
+ <p align="center">
6
+ <a href="https://www.npmjs.com/package/@waq666/pneuma"><img src="https://img.shields.io/npm/v/@waq666/pneuma?style=flat-square&label=npm&color=cb3837" alt="npm"></a>
7
+ <a href="https://github.com/waq05/pneuma/actions/workflows/release.yml"><img src="https://github.com/waq05/pneuma/actions/workflows/release.yml/badge.svg?branch=main" alt="Release"></a>
8
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License: MIT"></a>
9
+ <a href="package.json"><img src="https://img.shields.io/badge/node-%E2%89%A5%2022.19-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node >= 22.19"></a>
10
+ </p>
11
+
12
+ # Pneuma
13
+
14
+ > **全自研**的终端 AI 编程助手:自写 ReAct loop + 会话落盘 + 工具栈 + 审批,UI 用 ink(React for CLI),另有 Electron 桌面端;插件装配基于开源 cordis 上下文内核。
15
+
16
+ ## 有什么
17
+
18
+ - **一颗内核,三种前端** — 终端 TUI、Electron 桌面端(默认已是插件化界面壳)、**手机浏览器遥控页**;局域网扫码配对,人在外面也能批卡、看进度、发消息(PWA + Web Push + Webhook)。
19
+ - **模型自由** — 多端点 / 多模型随意切;上下文窗口、思考档位、图片 / 视频模态逐模型配置并可就地实测。输入框底栏两颗 chip 直接换模型与思考强度。
20
+ - **智能体协作** — 子智能体、智能体团队(并行队友 + 收件箱 + 汇报)、任务清单、计划交付、跨轮目标续跑。
21
+ - **长期记忆** — 跨会话事实分「全局 / 用户偏好 / 工作区」三格,当轮生效,可评估、可整理。
22
+ - **插件化** — 每个服务一个 cordis 插件;官方 18 个可开关插件(见 [§插件](#插件))+ 单文件 ESM 第三方插件;桌面界面壳本身也是插件架构(带 SDK)。
23
+ - **安全默认** — 写 / 执行一律过审批卡(一次授权一次生效);沙箱策略围栏、危险命令灾难地板;「沙箱三档」与「谁来审」是两个正交的旋钮(见 [§权限与安全边界](#权限与安全边界))。
24
+ - **长会话省 token** — 旧工具结果按轮微压缩、历史图片按预算卸载、压缩前回插读过的文件、端点侧显式缓存断点。
25
+
26
+ ## 快速开始
27
+
28
+ ### 桌面端
29
+
30
+ 自带运行时,不用装 Node:到 [Releases](https://github.com/waq05/pneuma/releases) 下载安装版
31
+ `pneuma-setup-x.y.z.exe`(可选安装目录)或免安装单文件 `pneuma-portable-x.y.z.exe`。
32
+
33
+ ### CLI(`numa`)
34
+
35
+ 需要 Node.js ≥ 22.19:
36
+
37
+ ```sh
38
+ npm i -g @waq666/pneuma # 或免安装:npx @waq666/pneuma
39
+ numa # 独立启动(新会话)
40
+ ```
41
+
42
+ `numa --resume` 恢复上次会话;`numa --resume <会话jsonl路径>` 恢复指定会话。
43
+
44
+ ### 从源码跑
45
+
46
+ ```sh
47
+ git clone https://github.com/waq05/pneuma
48
+ cd pneuma && pnpm install && pnpm build
49
+ npm i -g file:. # 全局 numa 命令指向本地构建
50
+ ```
51
+
52
+ ## 快捷键与斜杠命令
53
+
54
+ | 按键 / 命令 | 作用 |
55
+ | --- | --- |
56
+ | 直接输入 + Enter | 发送消息 |
57
+ | 输入 `/` 后 | 输入框上方弹出候选面板:命令阶段列命令,`/model ` 后列**可用模型**(↑↓ 选择、Tab 补全、Esc 关闭) |
58
+ | ↑ / ↓(空输入时) | 翻输入历史 |
59
+ | Ctrl+C | 一次:打断当前回合;2 秒内两次:退出 |
60
+ | Ctrl+T | 展开/折叠思考(reasoning) |
61
+ | `/new` | 新建会话 |
62
+ | `/resume` | 恢复历史会话(↑↓ 选择,Enter 确认,Esc 取消) |
63
+ | `/compact` | 手动压缩上下文(自动阈值:估算 tokens > 80% × 模型上下文窗口) |
64
+ | `/model [端点/]模型名` | 切换模型(下一次请求生效;候选来自配置里的全部 provider/model) |
65
+ | 桌面端 Ctrl+V / 拖文件 | 把图片贴进输入框,随这条消息一起发出(模型没勾「照片」会被拒绝,见 [§配置](#配置)) |
66
+ | 桌面端双击待发贴图 | 全屏预览大图(点任意处或 Esc 关闭);贴图在会话切换后各回各的,不会串到别的会话 |
67
+ | `/help` `/exit` | 帮助 / 退出 |
68
+
69
+ 面板打开时按 Enter 会采用当前选中项;命令名还支持**唯一前缀自动展开**(输入 `/ne` 按 Enter 即执行 `/new`)。
70
+
71
+ 工具授权卡出现时:`y` 允许一次,`n`(或 Esc)拒绝。卡只弹在发起它的那个会话里——后台会话的卡不串到当前视图,切回去(状态点会亮)再答。
72
+
73
+ ## 工具集(10 件)
74
+
75
+ `bash`(PowerShell)、`read`、`write`、`edit`(唯一匹配替换)、`glob`、`grep` 六件核心读写搜索工具;
76
+ 另有 4 件:后台作业三件套 `job_output` / `job_list` / `job_kill`,以及交互终端 `terminal`。
77
+ 读类工具自动放行;**写/执行类必须过审批卡**(无持久授权,一次授权一次生效)。
78
+
79
+ ## 配置
80
+
81
+ Pneuma 只读**自己的**配置文件(`~/.dsc/`):
82
+
83
+ - **`~/.dsc/config.yaml`**(主配置):`default`(默认 provider/model)+ `providers`
84
+ (`displayName` / `baseURL` / `apiKeyEnv` / `models` 列表;可选 `api` 选线上协议适配器,
85
+ 缺省 `openai-compat` 风格的 `openai-completions`,装了提供别的协议的插件后可换)。
86
+ - **模型可选字段**(不写就用默认,设置界面「模型」分区每个模型一行可直接改):
87
+
88
+ ```yaml
89
+ models:
90
+ - id: hy3-a
91
+ contextWindow: 200000 # 上下文窗口(用于压缩阈值与侧栏显示)
92
+ maxTokens: 32000 # 单次输出上限
93
+ thinkingLevels: [off, low, max] # 这个模型支持哪几档思考(默认四档 off/low/high/max)
94
+ thinkingParam: reasoning-effort # 档位发哪个字段:thinking / reasoning-effort / none
95
+ effortMap: { low: minimal, max: ultra_max } # 各档发给端点的线上值(写 null = 不发字段)
96
+ modalities: [text, image] # 能收什么输入:text / image / video
97
+ ```
98
+
99
+ `thinkingParam` 默认 `thinking`(只有开关、无档位字段的协议),此时低/高/最大都发 `thinking: enabled`;
100
+ 网关按档位取值的(发 `reasoning_effort`)要显式写成 `reasoning-effort`,界面上的思考档位才会真的生效。
101
+ `modalities` 没写 `image` 的模型,界面上贴图会被直接拒绝。
102
+ - **key 来源顺序**:`apiKeyEnv` 指向的环境变量 → `~/.dsc/credentials.yaml`。代码绝不打印 key。
103
+ - **`~/.dsc/config.json`**(可选轻量覆盖):`{ "provider": "...", "model": "...", "temperature": 0.7 }`。
104
+
105
+ ```sh
106
+ numa config show # 查看当前生效的端点/模型/key 来源(不打印 key)
107
+ ```
108
+
109
+ - **会话落盘**:`~/.dsc/sessions/<cwd 压缩名>/<uuid>.jsonl`(append-only,重放恢复);
110
+ `~/.dsc/.last-session` 是 `--resume` 无参时的指针。
111
+
112
+ ## 插件
113
+
114
+ 每个服务一个 cordis 插件。官方可开关插件共 **18 个**(默认开:网页搜索、审批灾难地板、大输出溢出、会话全文检索、沙箱、文件更改预览;默认关:子智能体、智能体团队、电脑操作、生命周期钩子、MCP 客户端、工具渐进披露、定时任务、LSP 代码智能、浏览器自动化、侧栏浏览器控制、自我改进、dsh 兼容层等),在插件中心里手动开关;长期记忆是默认开的内核插件。完整清单与各自干什么见 [docs/development.md](docs/development.md) 第 4 节。
115
+
116
+ 外部插件 = 单个 ESM `.js` 文件放进 `~/.dsc/plugins/`,可注册工具、命令、监听事件,
117
+ 桌面端「插件」页可视化管理。完整 API 与开发规范见 **[docs/plugin-development.md](docs/plugin-development.md)**,上手路径与扩展点速查见 **[docs/writing-plugins.md](docs/writing-plugins.md)**;可运行示例见 `examples/plugins/ping.js`。
118
+
119
+ ## 架构
120
+
121
+ 一条消息的旅程:
122
+
123
+ ```
124
+ 你的一句话 → ReAct 循环(流式)→ 写/执行类先过审批卡 → 工具 → 定稿 → JSONL 落盘 → 界面快照
125
+ ```
126
+
127
+ ```
128
+ bin/dsc.js 启动器(零依赖):--resume / config 子命令 → spawn node lib/boot.js
129
+ src/boot.ts 进程入口:读配置 → createKernel()(cordis 装配)→ 装 UI 插件
130
+ src/tools/config-cli.ts numa config 命令行工具
131
+ src/core/ 自研引擎(零 UI 依赖)
132
+ config.ts 读 ~/.dsc/config.yaml + key 来源链(env → 凭据文件)
133
+ llm.ts OpenAI chat-completions 流式客户端(SSE/reasoning/tool_calls/usage/重试)
134
+ session.ts JSONL 会话(append-only + 重放恢复)
135
+ loop.ts MiniAgent ReAct 循环(turn → stream → 审批 → 工具 → 定稿)
136
+ tools/ bash/read/write/edit/glob/grep 注册表
137
+ approval.ts 写/执行类挂起等 y/n
138
+ compact.ts 保头折尾摘要压缩
139
+ src/adapter/ core 事件 → 快照投影(transcript 折叠 + core-runtime)
140
+ src/contract.ts UI ⇄ 运行时 的中性契约(DscRuntime)
141
+ src/host/kernel.ts 内核装配顺序 + 三档插件清单(运行内核 / 官方可开关 / 自定义)
142
+ src/plugins/ 每个服务一个 cordis 插件(含官方可开关插件,见上文清单)
143
+ src/app/ ink UI(App/ChatView/Composer/ToolCard/ApprovalCard/SessionPicker/StatusBar)
144
+ desktop/ Electron 桌面端:主进程 + 独立运行时子进程;界面默认加载壳产物,可回退旧渲染层
145
+ ui-shell/ 桌面与手机共用的界面壳(插件化:布局 + 基元 + 官方界面插件;产物落 lib/ui/assets)
146
+ scripts/composer-test.mjs 候选面板/输入行的确定性测试(node scripts/composer-test.mjs,16 项断言)
147
+ ```
148
+
149
+ **模式(Agent 预设)**:一根独立的旋钮,决定模型是谁、手上有什么、被叮嘱了什么(提示词 + 工具目录)。出厂四个——标准 / 极简 / 创造 / PTC,自己加的模式就是 `~/.dsc/presets/<名字>.md` 一个文件,设置页可图形编辑,输入框下方那颗旋钮或 `/preset <名字>` 切换。模式**只做减法**(工具白名单取子集、提示段只能摘掉四段),任何模式都放宽不了安全。详见 [docs/presets.md](docs/presets.md)。
150
+
151
+ ## 权限与安全边界
152
+
153
+ 三件事叠在一起,越靠后越硬:
154
+
155
+ - **权限预设(出厂四个)** — 只读 / 工作区可写(默认)/ 完全访问 / 自动审查。「沙箱三档」(只读 / 工作区可写 / 不设围栏)与「谁来审」(**本人** / **模型**)是两个正交的旋钮,四个预设就是它们的出厂组合;要微调就逐格改,会落到 `custom`。
156
+ - **审批卡** — 区外写入与命令一律挂起等你按 `y` / `n`,**一次授权一次生效**,没有持久授权。
157
+ - **灾难地板** — 危险命令(格式化磁盘、递归删根、`git push --force` 之类)即使选了「完全访问」也直接拒。
158
+
159
+ **边界要说清楚**:沙箱是策略围栏(默认开的 sandbox 插件:可写根白名单、受保护路径、命令前缀策略、一次性升权),拦得住 Pneuma 自己发起的工具调用,**拦不住命令内部的任意写**——那要选容器后端;最终兜底仍是审批卡。
160
+
161
+ ## 已知限制
162
+
163
+ - 插件能加工具、命令、事件监听、设置分区和技能来源,但拿不到 DOM:界面扩展只接受可 JSON 序列化的控件声明。
164
+ - Windows 中文输入法可能拦截审批卡的 y/n 键(输入法切英文即可)。
165
+ - **电脑控制**(无障碍元素级点击 / 拖拽 / 截图)目前仅 Windows,且没接沙箱——动作按危险分级审计,最终仍过审批卡。
166
+ - 跨进程的路由状态(当前模型/思考强度)不落盘,重启宿主后回到配置默认值。
167
+
168
+ ## 开发
169
+
170
+ ```sh
171
+ pnpm install
172
+ pnpm build # 编内部引擎与宿主(tsc → lib/)
173
+ pnpm build:ui # 编桌面 / 手机共用的界面壳(产物落 lib/ui/assets)
174
+ pnpm typecheck
175
+ pnpm dev # tsc --watch
176
+
177
+ node scripts/composer-test.mjs # 自检:scripts/ 下每个 *-test.mjs 都是一个能单独跑的无头脚本
178
+ cd desktop && pnpm dev # 桌面端(先把上面两条 build 跑过)
179
+ ```
180
+
181
+ 桌面端的进程分层、宿主 ⇄ 壳协议与打包流程见 [desktop/README.md](desktop/README.md)。
182
+
183
+ ## 文档
184
+
185
+ | 文档 | 讲什么 |
186
+ | --- | --- |
187
+ | [docs/development.md](docs/development.md) | 开发手册:运行时结构、三条启动链路、进程间协议、`~/.dsc` 数据面、扩展点清单、自检与打包、代码约定、排错与关键数值 |
188
+ | [docs/development-log.md](docs/development-log.md) | 开发记录:各阶段引入了什么、决策台账、真 bug 台账、还欠什么 |
189
+ | [docs/plugin-development.md](docs/plugin-development.md) | 插件 API 与开发规范(规格书:全表签名、dsh 兼容层、界面插件契约) |
190
+ | [docs/writing-plugins.md](docs/writing-plugins.md) | 写一个插件:选形态、跑通最小链路、扩展点速查、交付自检 |
191
+ | [docs/presets.md](docs/presets.md) | **模式(Agent 预设)**:模式文件怎么写、出厂四个各是什么、可去掉哪些提示段、四条硬规矩 |
192
+ | [docs/ui-design.md](docs/ui-design.md) | 界面开发规范:设计原则、令牌体系、原语层、布局与反馈、键盘与动效、主题引擎对照 |
193
+
194
+ 其余文档按用途分三类:
195
+
196
+ **活参考与现状说明**:[docs/harness-benchmark-roadmap.md](docs/harness-benchmark-roadmap.md)(对标差距与路线图)、[docs/peer-feature-inventory.md](docs/peer-feature-inventory.md)(三家功能面清单)、[docs/remote-tunnel.md](docs/remote-tunnel.md)(遥控端口走隧道)、[docs/ui-shell-parity-audit.md](docs/ui-shell-parity-audit.md)(界面壳 vs 旧桌面版逐项对照)、[docs/ui-model-picker.md](docs/ui-model-picker.md)(输入区模型与档位选择)
197
+
198
+ **已完成的历史计划与施工书**:[docs/context-token-plan.md](docs/context-token-plan.md)(上下文与 token 优化)、[docs/dock-browser-control.md](docs/dock-browser-control.md)(侧栏浏览器控制)、[docs/plugin-runtime-parity-plan.md](docs/plugin-runtime-parity-plan.md)(插件运行时分批与懒物化)、[docs/ui-plugin-parity-plan.md](docs/ui-plugin-parity-plan.md)(桌面界面插件化)、[docs/ui-motion-options.md](docs/ui-motion-options.md)(整轮折叠动效选型)
199
+
200
+ **外部实现拆解与调查存档**:[docs/codex-request-assembly.md](docs/codex-request-assembly.md)、[docs/dsh-request-assembly.md](docs/dsh-request-assembly.md)、[docs/dsh-plugin-porting.md](docs/dsh-plugin-porting.md)、[docs/opencode-go-session-header.md](docs/opencode-go-session-header.md)
201
+
202
+ 已归档的旧计划在 [docs/archive/](docs/archive/)(会话折叠清单、TUI 适配计划、TUI 视觉对齐计划)。
203
+
204
+ ## 许可
205
+
206
+ MIT,见 [LICENSE](LICENSE)。问题与建议走 [Issues](https://github.com/waq05/pneuma/issues)。
package/lib/app/App.d.ts CHANGED
@@ -2,7 +2,7 @@ import type { JSX, ReactNode } from 'react';
2
2
  import type { DscRuntime } from '../contract.js';
3
3
  import { type ClipboardResult } from './clipboard-image.js';
4
4
  import { renderImageBlock } from './image-blocks.js';
5
- export declare function App({ runtime, clipboardReader, imageRenderer, tuiNoticeExtras, }: {
5
+ export declare function App({ runtime, clipboardReader, imageRenderer, tuiNoticeExtras, snapshotMs, }: {
6
6
  runtime: DscRuntime;
7
7
  /** 剪贴板读取(测试注入口;省略用 PowerShell 真实现)。 */
8
8
  clipboardReader?: () => Promise<ClipboardResult>;
@@ -10,4 +10,6 @@ export declare function App({ runtime, clipboardReader, imageRenderer, tuiNotice
10
10
  imageRenderer?: typeof renderImageBlock;
11
11
  /** 界面插件贡献的通知区扩展块(阶段 6;终端插件装载后传入,测试不传就没有这一块)。 */
12
12
  tuiNoticeExtras?: ReactNode;
13
+ /** 快照合并窗口(测试注入口:0 = 直通,用来在同一场里量「不合并会怎样」)。 */
14
+ snapshotMs?: number;
13
15
  }): JSX.Element;