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）即自动加载。

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 模板里的文件名同步变更），建议结合删除目录来升级版本。