JPCode 使用文档

1. 安装与运行

1.1 安装包安装（Windows）

从发布目录获取 jpcode_setup.exe（单文件，已内嵌 JPCode 及全部运行库），双击运行安装向导： 欢迎页 → 安装位置 → 进度页 → 完成页，安装后桌面出现 JPCode 快捷方式，可从「应用和功能」正常卸载。

1.2 macOS 安装

获取 macOS 安装包并拖入「应用程序」，首次打开若提示开发者验证， 在「系统设置 → 隐私与安全性」中允许即可。渲染默认 Metal。

1.4 渲染后端

默认按 DX12 → Vulkan → DX11 → null 依次尝试；可用 JP_BACKEND 环境变量或 --backend 参数指定。

2. 快速开始

1. 启动 JPCode → 左侧「设置」→ AI 页选择服务商，填写 API Key（可留空使用环境变量）。
2. 底部工具条选择模型与思考模式（关闭 / 低 / 中 / 高）。
3. 在底部输入框输入问题，回车或点「发送」。

API Key 可通过服务商对应的环境变量提供（优先级高于界面配置）： OPENAI_API_KEY、DEEPSEEK_API_KEY、ZHIPU_API_KEY、MOONSHOT_API_KEY、 DASHSCOPE_API_KEY、ARK_API_KEY、TOKENHUB_API_KEY 等。

3. 界面说明

• 会话列表：左侧栏，可折叠 / 宽度拖拽；子代理会话以紫色标题显示，状态点紫色 = AI 回复中、蓝色 = 命令执行中。
• 标题栏：会话名、工作目录、SSH 远程目录；显示 token 用量、上下文占用（超限标黄）与文件修改统计。
• 消息区：对话气泡；「思考过程」默认收起，点击展开。
• 底部工具条：模型、思考模式、目标机器（本机 / SSH）、常用命令、技能开关。
• 附件：输入框左侧「＋」选择文件，发送时自动附加内容（文本 ≤8KB/个、共 30KB，二进制只附路径）。
• Git 审查面板：变更文件树 + diff 对比 + Markdown 预览，宽度可拖拽并持久化。

4. AI 对话

4.1 服务商预设

注：火山方舟（Coding Plan / Agent Plan）默认走 Chat Completions API。

切换预设时自动填充 base_url 与常用模型；自定义供应商支持填写名称、Base URL、Key、模型与 API 形态。 代理支持 http://、socks4://、socks5://（含认证），作用于所有 AI 请求（含 SSE 流式）。

4.2 上下文检测与自动续接

按会话估算上下文 token 并用 API 实际 usage 校准，超限标黄；发送前检测超限自动开新会话无缝承接（默认上限 128000，可在设置页调整）。

4.3 技能（skill）

技能是指令注入，可按会话独立开关。内置：代码审查、测试编写、文档撰写、通俗解释、安全检查、规划并行（默认开启）。 自定义 / 第三方技能放入 %USERPROFILE%\.jpcode\skills\（*.md / *.txt）即自动加载。详见 14. 自定义技能开发。

5. 命令执行

5.1 本机执行

!git status
!Get-ChildItem | Select-Object -First 5

以 ! 开头回车即执行本机 PowerShell（macOS 为 zsh），stdout/stderr 实时回流； 执行前后自动 diff 工作目录快照，追加文件变更统计（+N ~M -K）。

5.2 SSH 远程执行

!ssh uname -a    # 远程执行（空参数 = 连通性测试）

支持设置页配置主机或直接使用 ~/.ssh/config 的 Host 别名；支持 Linux / macOS / Windows 目标机，自动适配语法，可设远程工作目录。

# ~/.ssh/config
Host test
  HostName 192.168.10.8
  User jp
  IdentityFile ~/.ssh/id_ed25519

5.3 控制指令

设置页可配置命令确认策略（全部允许 / 执行时询问）与常用命令库一键执行。

6. 多会话与 subagent

多会话并行：每个会话独立持有 AI 客户端与命令执行器，切换 / 新建不打断其它会话。

/agent 审查当前项目的 CMake 配置
/subagent 总结最近的 git 改动

派生子代理会话（继承最近 12 条上下文）→ 后台并行运行 → 完成后结果自动写回父会话，侧边栏紫色标题显示。

7. 任务队列

输入框「入队」编排多条任务，按顺序依次发送；每条可编辑 / 删除。 「SubAgent」把全部队列任务各派一个子代理并行执行；「GitPush」执行 add → commit → push。

8. Git 审查面板

• Git 审查：变更文件树（M/A/D/R/?? 状态色）+ 未暂存与已暂存 diff 对比（新增绿 / 删除红）。
• Markdown 预览：预览 .md 文件（单文件上限 2MB，按宽度缓存）。

9. 工具集

10. KV 缓存数据库

独立 KV 缓存进程 jpcode_kv_cache.exe，应用经 IPC 访问（Windows 命名管道 / macOS Unix domain socket ~/.jpcode/cache/kv.sock），用于代码识别结果缓存等键值存储。

11. 数据与配置文件

12. 常见问题（FAQ）

流式回复没有输出？

确认服务商支持 SSE 且 API 形态正确；OpenAI 兼容服务商可在自定义供应商里切换 Responses ↔ Chat。

连接失败 / 超时？

检查代理配置（http:// / socks5://）；查看 jpcode_error.log 与 jpcode_ai.log。

API Key 报鉴权错误？

确认 Key 与服务商匹配（尤其千问AI sk-ws- 与 Token Plan sk-sp- 不可混用），或改用对应环境变量。

上下文超限？

会自动开新会话续接；也可在设置页调整上限（默认 128000）。

命令执行没有反应？

检查命令确认策略（「执行时询问」会先弹窗）；SSH 执行先用 !ssh（空参数）测试连通性。

渲染异常 / 黑屏？

用 --backend dx11 或 --backend null 排除后端问题；查看 jpcode_error.log。

13. 自定义工具（Custom Tools）

JPCode 支持用户自定义工具。自定义工具是一个命令模板工具：在 config.json 里声明工具名、说明、命令模板与参数，JPCode 会把它作为 OpenAI function calling 的工具随请求声明给模型；模型决定调用时，JPCode 把模型返回的实参替换进命令模板的 {{param}} 占位符，以本地脚本模式执行，并把输出回传给模型。

13.1 配置文件位置

自定义工具保存在用户配置目录下的 config.json（Windows：%USERPROFILE%\.jpcode\config.json；macOS / Linux：~/.jpcode/config.json），对应键为顶层数组 "custom_tools"（与 "ai"、"window" 等字段平级）。也可以在设置页修改后由程序自动写回（原子写入，保留其余字段）。

13.2 配置格式（Schema）

{
  "custom_tools": [
    {
      "name": "get_weather",
      "description": "查询指定城市的当前天气",
      "command": "tools/weather.exe --city {{city}} --unit {{unit}}",
      "params": [
        { "name": "city", "description": "城市名称，如 北京" },
        { "name": "unit", "description": "温度单位：celsius 或 fahrenheit" }
      ]
    }
  ]
}

13.3 工作原理

1. 加载：JPCode 启动时读取 custom_tools 并注入 AI 层。
2. 声明：每次对话请求，每个自定义工具生成为 function calling 声明：参数统一为 string 类型，required 包含全部参数；开启「工具 strict」时按 OpenAI strict 模式生成（strict: true、所有属性 required、additionalProperties: false）。
3. 调用：模型返回 tool_call 后，按 call.name 查找自定义工具；命中则把 arguments JSON 中与参数名匹配的字符串值替换进模板的 {{参数名}} 占位符，未提供的参数替换为空字符串。
4. 执行：渲染出的命令走本地脚本执行器（PowerShell / 跨平台 PsRunner），与内置 run_command 相同；支持 SSH 时可在目标机远程执行。输出实时流式回显到会话，并以 role=tool 消息回传给模型继续推理。

13.4 编写示例

无参数工具：

{
  "name": "list_ports",
  "description": "列出本机当前监听的 TCP 端口",
  "command": "netstat -ano | findstr LISTENING",
  "params": []
}

多参数工具：

{
  "name": "git_log",
  "description": "查看某个仓库的最近提交",
  "command": "git -C {{repo}} log --oneline -n {{count}}",
  "params": [
    { "name": "repo",  "description": "仓库本地路径" },
    { "name": "count", "description": "返回条数，如 10" }
  ]
}

模型返回 {"repo": "D:/work/demo", "count": "5"} 时，实际执行 git -C D:/work/demo log --oneline -n 5。

调用脚本 / 可执行文件：

{
  "name": "translate_file",
  "description": "把文本文件内容翻译为英文",
  "command": "python tools/translate.py --file {{file}} --lang {{lang}}",
  "params": [
    { "name": "file", "description": "待翻译文件路径" },
    { "name": "lang", "description": "目标语言，如 en" }
  ]
}

13.5 开发注意事项

• 命名唯一：与内置工具（run_command、read_file、write_file、patch_file、fetch_page 等）或其他自定义工具重名时行为未定义，请使用独立前缀，如 my_。
• 参数都是字符串：只有 arguments 中的字符串值会被替换；数字 / 布尔等类型按空串处理。命令模板内请自行处理引号。
• 占位符必须声明：{{xxx}} 中的 xxx 必须出现在 params[].name 中，否则不会被替换。
• 注入风险：命令模板与实参拼接后直接执行，description 里应约束参数形态（如「只允许文件路径」），避免把不可信输入交给模型自由填写。
• 输出回传：标准输出与标准错误都会回传模型，长输出建议在脚本内截断。
• 编码：配置文件为 UTF-8（允许带 BOM）；命令输出中的非法字节会被消毒为 U+FFFD，避免破坏会话 JSON。
• 生效时机：修改 config.json 后需重启 JPCode（工具在启动时加载注入）；程序内部保存后立即生效。

13.6 自定义工具下载地址（url）

自定义工具支持可选的 url 字段：把工具的脚本 / 可执行文件托管在 HTTP(S) 地址上，JPCode 会在启动时与工具执行前自动下载到本地安装目录，实现「声明即分发」。

{
  "custom_tools": [
    {
      "name": "repo_stat",
      "description": "统计当前仓库代码行数（首次调用自动下载工具脚本）",
      "url": "https://example.com/jptools/repo_stat.py",
      "command": "python {{tool_dir}}/repo_stat.py {{path}}",
      "params": [
        { "name": "path", "description": "仓库路径" }
      ]
    }
  ]
}

新增字段：

安装目录与生命周期：

• 安装目录：~/.jpcode/tools/<工具名>/，下载的文件以 URL 路径末段命名（自动去掉 query / fragment），例如保存为 ~/.jpcode/tools/repo_stat/repo_stat.py。
• 启动预下载：启动加载 custom_tools 后，后台线程对每个带 url 的工具执行下载（已存在则跳过，不阻塞 UI）。
• 执行时保障：模型调用工具时再次校验安装目录；文件缺失则同步下载，下载失败会把 custom tool download failed: ... 作为工具输出回传给模型。
• 不覆盖更新：本地同名文件已存在时直接复用。需要更新时删除 ~/.jpcode/tools/<工具名>/ 下对应文件（或整个目录）即可触发重新下载。

实现要点：下载经 httpclient 的 HttpClient（HTTP/1.1 ~ HTTP/3，自动 TLS 与重定向），同步等待、超时 60 秒；下载成功先写临时文件再原子替换。命令渲染时支持两种占位符：{{param}}（模型实参）与 {{tool_dir}}（安装目录）。

注意事项：目前仅支持单文件下载，多文件依赖请打进一个自解压脚本或在 command 里自行处理；仅支持 HTTP/HTTPS 明文直链，带鉴权的地址需 URL 自带 token 或改用内网可直连的镜像；下载地址应固定文件名（带版本号的文件名会导致 command 模板里的文件名同步变更），建议结合删除目录来升级版本。

14. 自定义技能开发

JPCode 的技能（Skill）是一段注入给 AI 的指令/规则，用于让模型按特定方式工作（如代码审查、测试编写、文档撰写、视觉操作等）。技能可以多个并存，按会话单独启用，启用后其指令会随请求一起注入给模型。本文说明 JPCode 的技能体系，以及如何添加一个或多个自定义技能。

14.1 技能体系总览

JPCode 的技能分三类，三者会在输入栏「技能」下拉中一起列出：

三者都会出现在同一个下拉里，并且可以同时启用多个。

14.2 添加多个自定义技能

方式一：手动放置 .md 文件（推荐，便于批量）

在技能目录下每个文件放一个技能，多个技能就是多个文件：

~/.jpcode/skills/
├── 代码审查.md
├── 写文案.md
├── 整理笔记.md
└── 生成周报.md

• Windows：%USERPROFILE%\.jpcode\skills\
• macOS / Linux：~/.jpcode/skills/

LoadThirdPartySkills 会扫描该目录下所有顶层 .md / .txt 文件，全部加载（放 N 个就是 N 个技能），并在「技能」下拉中全部列出。

文件格式（推荐带 frontmatter）：

---
id: my_code_review
name: 我的代码审查
---
对提交的代码进行逐行审查：先看正确性，再看健壮性与安全，
按严重程度分级（严重 / 一般 / 建议）给出修改建议。

没有 frontmatter 也可以：直接写正文，id/name 会用文件名（去掉 .md）代替。

方式二：设置面板添加（存到 config.json）

设置面板 →「技能」标签页 → 在底部输入「技能名」和「指令内容」→ 点「添加」。

• 会写入 ~/.jpcode/config.json 的顶层 skills 数组，多个技能就是多个数组元素。
• 格式（与手动编辑一致）：

{
  "skills": [
    {
      "id": "my_skill",
      "name": "我的技能",
      "instruction": "注入给模型的规则，不能为空"
    }
  ]
}

14.3 两种方式的区别

14.4 加载时机

• 启动时：JPCode 初始化时分别加载 config.json 的 skills（customSkills_）和 ~/.jpcode/skills/ 目录（thirdPartySkills_）。
• 打开下拉时：技能下拉每次打开会重新扫描 ~/.jpcode/skills/ 目录，因此手动放置 .md 后无需重启，点开下拉即可看到（v1.0.6x+）。
• config.json 里的 skills 若手工编辑，仍建议重启生效。

14.5 技能下拉：显示与启用

三类技能统一列在输入栏「技能」下拉中；勾选即对当前会话启用，可同时启用多个，启用后指令随请求一并注入。第三方技能在下拉打开时重扫目录，新增 / 删除 .md 文件即时生效。

15. JAC-1.1 通信标准 与 Response API

15.1 JAC-1.1 侏罗纪AI通信标准

JAC-1.1（Jurassic AI Communication Standard，侏罗纪AI通信标准）是由 侏罗纪AI标准工作组（JASWG）发布的、运行于 WebSocket 之上的 JAI 实体间 JSON 应用层协议。文档编号 JAC-SPEC-1.1，状态：正式发布（Release）， 发布日期 2026-09-05。

1.1 相对 1.0 的增补（全部向下兼容）：新增 file.* 控制面消息族与 file.data 二进制数据帧（双向文件传输，§9.5）；能力声明 server_caps 新增 "file.transfer"；错误码新增 4403~4406；L2/L3 一致性等级纳入文件传输。

完整标准文本：已收录到本仓库 docs/JAC-1.1-jurassic-ai-communication-standard.md （共 17 章：范围与术语 / 核心模型 / 传输层 / 会话建立 / 消息格式 / 消息类型注册表 / 用户消息 / 工具定义与工具调用 / 代码模块与文件传输 / 流式输出与统计 / 心跳超时关闭 / 安全 / 一致性等级 / 附录 A~D）。需要完整条款、消息 JSON Schema、错误码表与会话示例时，请查阅该文档。

15.2 Response API 调用说明

JPCode 的 AI 接入服务提供 OpenAI Responses 兼容的 HTTP API（SSE 流式）， 可直接在自定义供应商 / 第三方程序中使用。Base URL：

https://ai.jurassic-period.com/

鉴权：HTTP 头 Authorization: Bearer <你的 API Key>。

① Responses 接口（默认推荐）：POST /v1/responses

curl https://ai.jurassic-period.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jurassic-1.1-tyranno",
    "input": "用中文介绍侏罗纪AI通信标准",
    "stream": true
  }'

② 在 JPCode 中配置为自定义供应商

流式响应：两个接口均返回 text/event-stream 的 SSE 数据， 事件类型遵循 OpenAI Responses 惯例（如 response.output_text.delta），末尾以 data: [DONE] 结束。

16. 第三方插件 SDK（第三方插件开发）

本章讲如何用工具包（tool package）形态交付第三方插件：一个包目录 = 清单 jpcode-tool.json + 设置页布局 tools_tab.json + 工具脚本。JPCode 扫描包目录后把工具 导入「设置 → 工具」，并把布局渲染成竖排表单；用户填完点「保存设置页」，值写进包目录下的 settings.json，工具脚本启动时自行读取。协议契约见 sdk/PROTOCOL.md， 设置页细则见 sdk/SETTINGS_PAGE.md。

16.1 SDK 位置与内容（随安装包分发）

SDK 随安装包分发（安装目录 sdk/ 内已包含，无需单独下载），装好 JPCode 后即可在安装目录内找到：

16.2 第三方插件（工具包）是什么

第三方插件就是一个普通文件夹，满足三点即被 JPCode 识别为工具包：

• 有清单：jpcode-tool.json，声明包名、标题与设置页位置；
• 有工具：脚本 / 可执行程序随包分发，无需编译进 JPCode；
• 可选设置页：一份 JPEngine JSON 页面布局（惯例文件名 tools_tab.json），让用户在图形界面里填参数。

端到端流程（设置页只负责「收参数」，不参与工具执行）：

包目录（jpcode-tool.json + tools_tab.json + 工具脚本）
        │  扫描（设置 → 工具，首次进入自动扫描 / 「重新扫描」）
        ▼
JPCode 校验 → 导入（工具进 config.json、设置页登记进 ~/.jpcode/tool_pages.json）
        │
        ▼
竖排表单渲染（先序拍平，几何字段忽略）→ 用户填写 → 「保存设置页」
        │
        ▼
<包目录>/settings.json（键 tp:<页 id>:<控件 id>）→ 工具脚本读取

16.3 包目录与清单 jpcode-tool.json

扫描根下的一级子目录各为一个包，清单、布局与脚本放在同一个目录：

my-tool/
├── jpcode-tool.json      # 清单（必需）
├── tools_tab.json        # 设置页布局（可选，惯例文件名）
├── settings.json         # 用户填写的值（「保存设置页」时生成）
└── my_tool.py            # 工具脚本（随包分发）

清单字段：

未声明 settings_page 时，按 tools_tab.json → settings_page.json → settings.json 顺序探测；三个文件名都没命中只告警（纯命令行工具包可以不提供设置页）。

16.4 设置页布局 tools_tab.json 与控件全表

布局是一份 JPEngine JSON 页面：顶层含 root 对象，或布局自身即根节点（自带 type / children）。 JPCode 把布局先序拍平成竖排表单逐控件呈现，呈现顺序由节点先后决定。

① 公共字段

② 类型对照表

③ 最小骨架模板（存成包内 tools_tab.json，再把清单的 settings_page 指向它）

{
  "root": {
    "id": "my_tool_page",
    "type": "vbox",
    "children": [
      {
        "id": "intro",
        "type": "markdown",
        "text": "填写后点「保存设置页」，值写入本包 settings.json（键 tp:my_tool_page:<控件 id>）。"
      },
      {
        "id": "api_key",
        "type": "input",
        "label": "API Key",
        "placeholder": "粘贴服务端 API Key",
        "text": "demo-key"
      },
      {
        "id": "endpoint",
        "type": "inputfield",
        "label": "服务地址",
        "placeholder": "https://example.com/api"
      },
      {
        "id": "verbose",
        "type": "checkbox",
        "text": "输出详细日志",
        "checked": true
      },
      {
        "id": "hint",
        "type": "text",
        "text": "提示：几何字段（rect / height / padding 等）会被忽略，无需书写。"
      },
      {
        "id": "actions",
        "type": "hbox",
        "children": [
          { "id": "save", "type": "button", "text": "保存" }
        ]
      }
    ]
  }
}

对照上表：intro（markdown）不落盘；api_key / endpoint 落盘键为 tp:my_tool_page:api_key / tp:my_tool_page:endpoint；verbose（checkbox） 落盘 "1" / "0"；actions 只是容器，其中 button 仅作视觉呈现。

16.5 页 id、标题与设置键规则

设置页 id（页 id）优先级从高到低：清单 settings_id → 布局根节点 id → <包名>_page（包名即清单 name）。

设置页标题优先级从高到低：根节点 title → 根节点 text → 清单 title → 清单 name。

设置键：所有落盘控件都按下面的键写进 <包目录>/settings.json：

tp:<页 id>:<控件 id>

例如 echo-package（settings_id = echo_tool_page）里输入框 echo_text 的键就是 tp:echo_tool_page:echo_text。settings.json 是一层扁平对象，只含 tp: 前缀的字符串键值 （JPCode 保存时会保留包内其它既有键）：

{
  "tp:echo_tool_page:echo_text": "hello",
  "tp:echo_tool_page:echo_prefix": ">> ",
  "tp:echo_tool_page:echo_strict": "1"
}

• 一层扁平键空间：键按页 id 分组，同一页内重复的控件 id 会互相覆盖；
• 再次打开同一设置页时按同一键回填；input 的 text 只在无存档时作为默认值。

16.6 校验规则与扫描根

导入时（以及点「重新扫描」时）逐包校验，全部通过才在列表里可用：

扫描根（存在即扫描；一级子目录各为一个包）：

16.7 本地自检（不启动 JPCode）

用随包分发的 sdk/tools/check_settings_page.py 离线校验（不启动 JPCode）：

python sdk/tools/check_settings_page.py <包目录|布局文件> [--page-id X] [--json]

• python sdk/tools/check_settings_page.py sdk/examples/echo-package：校验一个包目录（读清单 + 校验设置页布局）；
• python sdk/tools/check_settings_page.py sdk/examples/echo-package/tools_tab.json --page-id echo_tool_page：只校验一份布局文件，并显式给出页 id（用于算键）；
• --json：机器可读输出，便于接进 CI。

check_settings_page.py 退出码：

不依赖脚本的最简 JSON 自检（PowerShell）：

Get-Content -Raw -Encoding UTF8 sdk/examples/echo-package/tools_tab.json | ConvertFrom-Json

16.8 示例包 echo-package

sdk/examples/echo-package/ 是最小可用示例：清单 + tools_tab.json + echo.py + 自己的 README。 把整个目录复制到任一扫描根（如 ~/.jpcode/sdk/）后，进「设置 → 工具」点「重新扫描」即可看到设置页。

布局各节点解读：

保存后包内 settings.json 示例：

{
  "tp:echo_tool_page:echo_text": "hello",
  "tp:echo_tool_page:echo_prefix": ">> ",
  "tp:echo_tool_page:echo_strict": "1"
}

16.9 常见错误对照表

16.10 相关文件与进阶

• 协议契约：sdk/PROTOCOL.md（§5 目录约定、§6 工具包与设置页、§9.6 插件自有窗口——list / grid 只在该窗口渲染）；
• 设置页细则：sdk/SETTINGS_PAGE.md（本章口径与实现同源）；
• 示例包：sdk/examples/echo-package/（清单 + 布局 + echo.py + README）；
• 开发文档：docs/自定义工具开发文档.md 第 8 节（包格式总览）；
• 实现与用例：src/tool_pkg.h（解析 / 校验 / 拍平 / 设置合并）、src/settings.cpp（DrawToolsSettingsTab）、tests/tool_pkg_test.cpp（离线用例）。

进阶建议：先把 echo-package 跑通（扫描 → 导入 → 填表 → 保存 → 脚本读 settings.json）， 再替换成自己的 tools_tab.json 与脚本；每次改布局都用 16.7 的自检命令复核，避免导入阶段才发现问题。