1. AI agent
Agent模块负责处理request工作流，生成prompt与LLM交互。
Agent代码: http://ishangsf.com:8100/ken/agent
websocket接口地址: ws://47.117.75.243:8080/ws
接口文档: http://ishangsf.com:8100/ken/agent/src/branch/main/README.md
前端接口测试案例代码: http://ishangsf.com:8100/ken/agent/src/branch/main/examples
测试api_key: “simpletest2025_xxxx” xxxx为任意字符串
Agent 有三模式运行，由plugin在request的model参数决定，运行模式在交互过程对agent是透明的。
- agent local model：就是agent调用本地部署的LLM模型
- agent remote api：就是agent调用openai或deepseek等外部服务的api (改下llm就看实现)
- plugin remote api：由plugin调用openai或deepseek等外部服务的api (未实现，要改ideservice)
1.1 安装与运行
# linux
make
./build/bin/agent run
# windows
go build -o ../build/bin/agent.exe src/main.go
./build/bin/agent.exe run
1.2系统框架
ideservice 是须要plugin提供给agent的一些获取IDE信息的基础功能，为穿透NAT需要websocket连接。
1.3 workflow
sequenceDiagram
plugin->>agent: request
agent-->>ideservice: more info
ideservice-->>agent: file, symbol
agent->>plugin: result
agent有可能会多次向ideservice询问更多的信息，这对于plugin是透明的。
1.4 Task Pool
章节2中所有带cmd参数带前缀“exec”的request都是涉及LLM模型调用的。 Agent用一个FIFO队列缓存所有用户的未处理任务，当队列长度过大时agent会拒绝新来的任务。 同一APIkey同时能建立5个链接，一个连接只能有一个任务在队列，同时提交两个task, 前一个会被取消。
2. Agent协议
plugin通过websocket连接agent。如果使用https, 需要设置client接受agent的https认证证书。
2.1 身份认证
建立连接时带header "X-Api-Key" : api_key， 或 uri带api_key参数： ws://47.117.75.243:8080/ws?api_key=simpletest2025_001 如果api_key不对agent主动断开连接
let client = new ws.WebSocket('wss://host:8080/ws', {headers: {
["X-Api-Key"]: "simpletest2025_001",
}})
2.2 获取Agent支持的模型 （list_model）
request:
{
"request_id": 123, // 随机生成 （必填）
"cmd" : "list_model"
}
response:
{
"request_id": 123, // 同request
"models" : ["local deepseek-R1:32b", "deepseek-R1:32b"] // （必填）
}
2.3 生成代码解释 (exec_explain)
request:
{
"cmd" : "exec_explain",
"request_id" : 123, // 随机生成 （必填）
"language" : "en", // 语言, en-英文, zh-中文，默认为 en （可选）
"selected_text": text_context, // 选取的代码片段 （必填）
"visible_text" : text_context, // ide窗口可见的代码片段 （必填）
"model" : "local deepseek-r1:32b", //（必填）
"stream" : false // stream方式返回（可选）
}
text_context:
{
"filepath": "example\\\\game.py", // 文件路径
"range": {
"start": { "line": 33, "character": 0}, // 从33行0字符开始
"end" : { "line": 45, "character": 41} // 到45行41字符结束
},
"text": "..." // 源码片段
}
成功返回:
{
"request_id" : 123, // 同request（必填）
"msg" : "", // 返回内容
"stream_seq_id": 0, // stream=true时才有, 从0开始（可选）
"stream_finsh" : false, // stream=true时才有, true-stream结束（可选）
}
失败返回:
{
"request_id": 123, // 同request（必填）
"error" : "cancelled" // 出错信息，没有就是调用成功（必填）
}
2.4 生成代码文档 (exec_docstring)
目前只支持python
request:
{
"cmd" : "exec_docstring",
"request_id" : 123, // 随机生成 （必填）
"language" : "en", // 语言, en-英文, zh-中文，默认为 en （可选）
"selected_text": text_context, // 选取的代码片段 （必填）
"model" : "local deepseek-r1:32b", //（必填）
"stream" : false // stream方式返回 （可选）
}
返回json格式同 2.3
2.5 代码优化 (exec_optimize)
//TODO 未测试效果, prompt该如何描述优化？
request:
{
"cmd" : "exec_optimize",
"request_id" : 123, // 随机生成 （必填）
"language" : "en", // 语言, en-英文, zh-中文，默认为 en （可选）
"selected_text": "", // 选取的代码片段 （必填）
"model" : "local deepseek-r1:32b", //（必填）
"stream" : false // stream方式返回 （可选）
}
返回json格式同 2.3
2.6 生成单元测试代码 (exec_fix)
request:
{
"cmd" : "exec_fix",
"request_id" : 123, // 随机生成 （必填）
"language" : "en", // 语言, en-英文, zh-中文，默认为 en （可选）
"selected_text": "", // 选取的代码片段 （必填）
"model" : "local deepseek-r1:32b",//（必填）
"stream" : false // stream方式返回 （可选）
}
返回json格式同 2.3
2.7 生成单元测试代码 (exec_unittest)
// TODO 与ideservice交互
目前仅支持英文回复, 流程对devchat做了简化
sequenceDiagram
plugin->>agent: exec_unittest_recommend 请求测试建议
agent->>plugin: 测试建议
plugin->>agent: exec_unittest_code 请求测试代码
plugin->>agent: 测试代码
请求测试建议:
{
"cmd" : "exec_unittest_recommend",
"request_id": 123, // 随机生成 （必填）
"language" : "en", // 语言, en-英文, zh-中文，默认为 en （可选）
"user_prompt" : "", // 用户定制化描述 （可选）
"file_content" : "..." // 整个文件内容（必填）
"filepath" : "\\example\\game.py", // 文件路径（必填）
"func_name" : "next_turn", // 函数名 （必填）
"func_location": { // 函数位置（必填）
"start": { "line": 33, "character": 0},
"end" : { "line": 45, "character": 41},
},
"func_symbols": [ // function 内的所以变量名和函数名 （必填）
{
"name": "next_turn",
"kind": "Function",
"range": { // 位置
"start": { "line": 33, "character": 0},
"end" : { "line": 45, "character": 41}
},
"children": [
{
"name": "WIDTH",
"kind": "Constant",
"range": { // 位置
"start": { "line": 33, "character": 0},
"end" : { "line": 45, "character": 41}
},
"children": [
...
]
},
]
},
...
],
"model" : "local deepseek-r1:32b", //（必填）
"stream" : false // stream方式返回 （可选）
}
返回json格式同 2.3
请求测试代码：
{
"cmd" : "exec_unittest_code",
"request_id" : 123, // 随机生成 （必填）
"language" : "en", // 语言, en-英文, zh-中文，默认为 en （可选）
"test_cases_str": "", // exec_unittest_recommend 提供的 （必填）
// 如果task_id为空须填写：
"function_name" : "" // 函数名 （可选）
"user_prompt" : "" // 定制化描述 （可选）
"file_path" : "./src/test.py" // 文件在项目里的相对路径 （可选）
"relevant_content" : "" // the relevant source code of the function （可选）
"reference_content": "" // the relevant source code of the function （可选）
"stream": false // stream方式返回（可选）
}
返回json格式同 2.3
2.8 和大模型对话 (exec_chat)
request:
{
"cmd" : "exec_chat",
"request_id": 123, // 随机生成 （必填）
"msg" : "", // 内容 （必填）
"model" : "local deepseek-r1:32b", //（必填）
"stream" : false // stream方式返回（可选）
}
返回json格式同 2.3
3. ide_service协议
开发优先级低，解决2.7“与ideservice交互”问题前未用到
是由 agent 向 ide_service 请求，参考 https://github.com/devchat-ai/devchat-vscode/blob/main/src/ide_services/services.ts
只保留以下服务，
"/get_document_symbols": {
keys: ["abspath"],
handler: getDocumentSymbols,
},
"/find_def_locations": {
keys: ["abspath", "line", "character"],
handler: findDefinitionLocations,
},
"/find_type_def_locations": {
keys: ["abspath", "line", "character"],
handler: findTypeDefinitionLocations,
},
3. 功能覆盖
