# AICoding-01-提效 30%-60% 构建代码工程专属知识库，让自动化编程工具读懂你的项目

## 【 1. 从代码说明到程序知识库 】

以前 `README.md` 只是开源项目的代码声明，随着 Vibe Coding / AI Coding 的发展，`README.md` 不再只是代码注释，也不只是工程的说明文件，更是代码工程的门面，并被赋予了一定的功能性。但随着发展，`README.md` 和 `README.mdx` 慢慢变成只给人类查看的工程门面说明，于是独立出了 `CLAUDE.md`、`AGENTS.md`、`SOUL.md` 等专门给自动化 AI 编程工具查看的文档，形成了代码工程自己的知识库。

| 工具名称 | 自动读取的核心文件 |

| ---------------- | -------------------------------------------------- |

| Claude Code | - CLAUDE.md |

| Open Code | - AGENTS.md |

| OpenClaw | - SOUL.md、USER.md、AGENTS.md、TOOLS.md、MEMORY.md |

| Hermes Agent | - AGENTS.md |

| Codex CLI | - AGENTS.md |

| GrokCLI | - .grok/GROK.md |

| Cursor Agent CLI | - AGENTS.md |

| TRAE CLI | - AGENTS.md |

得益于 Claude Code 的行业示范，大多数工具都支持 `CLAUDE.md` 这类规范文件。代码工程在各个 AI 自动化工具间迁移时，只需重命名一下 `*.md` 文件即可完成一键迁移。

## 【 2. 传统代码工程改造（无知识库项目程序 Vibe Coding） 】

1. Claude Code、Open Code、OpenClaw、Hermes、Codex CLI、GrokCLI、Cline CLI、Cursor Agent CLI、TRAE CLI 等工具都具备初步的代码分析功能。拿到代码工程目录后，可以通过豆包、千问、Gemini 等在线大模型产品搜索相关解决方案，通过套娃方式逐步追加分析，无需读取全部文件，即可生成自己的知识库。

2. 如果代码工程没有自己的知识库，其实也是可以进行 Vibe Coding 的，只是提示词需要非常精确和复杂。例如：

// Start 方便阅读 ------------------------------------------------------------------------------------------

```markdown

# 这次重构的核心在于职责分离（Separation of Concerns）与面向 AI 的可观测性（AI-Oriented Observability）。

将原本集中在 debug_tool_runner.py 和 debug_tool_cdp_interceptor.py 中的庞杂逻辑，拆分为底层管控、实时探测、持久化监听和离线检索四大模块，这完美契合了“单文件不超过 1100 行”的强制约束，同时也让 Claude Code 未来的排查路径更加清晰。

# 一、 重构后的标准目录结构

为了实现闭环，重构后的 python-web-debug-tool 应当呈现如下结构：

````plaintext

python-web-debug-tool/

├── start_dev_env.py # [入口] 启动前端服务，输出访问地址

├── stop_dev_env.py # [入口] 停止前端服务

├── debug_tool_runner.py # [核心] 浏览器生命周期管理与 Playwright 监听挂载中心

├── debug_tool_realtime_dom.py # [实时] 获取当前 DOM 结构与 HTML

├── debug_tool_realtime_elements.py # [实时] 提取页面关键元素（表单、按钮、弹窗、错误树）

├── debug_tool_realtime_storage.py # [实时] 提取 Storage (Local/Session) 与 Cookie

├── debug_tool_realtime_snapshot.py # [实时] 获取当前 URL 与页面截图

├── debug_tool_pre_caching_network.py # [监听] 网络请求/响应持续捕获 (过滤特定 URL)

├── debug_tool_pre_caching_console.py # [监听] 控制台 Error 级别日志持续捕获

├── debug_tool_pre_caching_query_net.py # [工具] 网络请求的模糊匹配与报文检索工具

├── debug_tool_pre_caching_query_err.py # [工具] 历史 Error 日志的快速检索工具

├── logs/

│ └── session_YYYYMMDD_HHMMSS/ # 按启动会话隔离的日志目录

│ ├── summary.json # 会话元数据（AI 导航地图）

│ ├── pre_caching_network_index.log# 网络请求索引

│ ├── pre_caching_network_*.json # 网络接口详情数据块

│ └── pre_caching_console.log # 控制台错误收敛文件

└── .browser_ws.json # 浏览器连接与进程状态文件 (隐藏)

````

# 二、 核心模块逻辑设计与排查流程

## 1. 环境与浏览器管控层

1. start_dev_env.py & stop_dev_env.py

设计逻辑：剥离浏览器启动逻辑。start 仅负责执行 yarn start:pre，监听指定端口（20122），就绪后在控制台明确打印访问地址。stop 则负责根据端口或特定标识（PID）安全杀死 Node/Yarn 进程。

1. debug_tool_runner.py (浏览器大管家)

启动逻辑：使用 Playwright 启动 Chrome，必须携带 --remote-debugging-port 与专属标记（如 --claude-debug-tool）。启动后将 PID 和 WebSocket URL 写入 .browser_ws.json。

关闭逻辑：读取 .browser_ws.json 中的 PID，通过系统命令（如 `kill -9` 或 `taskkill`）定向查杀，或遍历进程树比对 `--claude-debug-tool` 参数，绝对禁止无差别 Kill Chrome，避免误杀用户私人标签页。

服务挂载：浏览器启动后，作为守护进程，实例化并注入 debug_tool_pre_caching_* 系列监听类。

## 2. 实时探测层 (debug_tool_realtime_*.py)

此类脚本设计为**按需触发（On-Demand）**的无状态脚本，由 Claude Code 在排查具体问题时即时调用。

1. 通信机制：读取 `.browser_ws.json` 获取 WebSocket 地址，通过 Playwright 的 connect_over_cdp 接入当前正在运行的调试浏览器。

2. 提取逻辑：

DOM/HTML：通过 page.content() 或评估 JS 获取当前渲染树，重点排查 Ant Design v4 的 DOM 挂载是否异常（如 Modal 挂载在 body 之外导致的失焦问题）。

Elements：利用 Playwright 的 Locator 机制，扫描特定的 DOM 节点（如 .ant-form, .ant-btn, .ant-modal, 或是带有特定业务类名的错误提示区块），返回结构化的元素树。

Storage：执行 page.context.cookies() 与 page.evaluate() 提取上下文凭证。

## 3. 异步监听与持久化层 (debug_tool_pre_caching_*.py)

此类模块随浏览器同生共死，实时过滤并落盘数据。

1. `_network.py` (网络监听与过滤)：

通过 page.on("request") 和 page.on("response") 注册钩子。

强制过滤规则：仅当 request.url.startswith("http://iam.woyunpoc.com:7092") 时进入处理分支，直接舍弃静态资源（js, css, png 等）、地图切片（BMapGL）和播放器分片（TS/FLV）的网络包。

数据切片落盘：为防止单文件过大导致 AI 读取超时（Token 爆炸），需要将请求的概要信息（URL, Method, Status, 耗时）追加写入 `pre_caching_network_index.log`（以 JSONL 格式）。而完整的 Request Body 与 Response Body 则以 Request ID 命名，序列化为 JSON 存入 `pre_caching_network_*.json`。

2. _console.py (日志监听)：

通过 page.on("console") 挂载，仅当 msg.type == "error"（或 exceptionThrown）时进行记录。屏蔽诸如 [mini-css-extract-plugin] Conflicting order 类的已知噪音。追加写入 pre_caching_console.log。

## 4. AI 智能检索层 (debug_tool_pre_caching_query_*.py)

作为 Claude Code 排查问题的“眼睛”和“手”，提供标准化入参接口。

1. `_query_net.py`：接收 url_pattern (模糊匹配), method 或 status_code 作为参数。

处理流：先读取最新的 `session_*/summary.json` 定位当前工作区 -> 扫描 `_index.log` 命中符合正则的 Request ID -> 读取对应的 `*.json` 报文文件 -> 输出清洗后的 JSON 给 AI 分析。

2. `_query_err.py`：读取 pre_caching_console.log，可按时间窗口或关键字过滤，提取 React 渲染异常或组件崩溃堆栈。

# 三、 废弃文件清理建议

由于架构升级与职责拆分，原有的几个“大杂烩”文件应当被清理，以防止规范冲突和代码冗余：

1. `debug_tool_cdp_interceptor.py` -> 清理/删除。其内部的 Console 和 Network 拦截逻辑已被拆分进 `debug_tool_pre_caching_*.py` 中。

2. `debug_tool_log.py` -> 降级或重构。考虑到现在的日志是按 Session 目录结构化归档，原先单例模式写死 `debug_tool_output.log` 的逻辑已不适用，应当重构为轻量级的目录生成器与 Logger 工厂。

# 四、 针对 Claude Code 的标准闭环工作流 (SOP)

为了确保调试有效，建议你在 Claude Code 中遵循以下排查闭环：

1. 启动环境：运行 `start_dev_env.py`，确认 20122 端口服务就绪。

2. 挂载诊断：运行 `debug_tool_runner.py` 唤起浏览器，此时底层的 pre-caching 监听自动开启，拦截 `iam.woyunpoc.com:7092` 的接口。

3. 触发异常：(人机协同) 提示用户在打开的浏览器中复现前端问题，或通过 Playwright 脚本自动触发。

4. 诊断执行：

如果是 UI 渲染 / React 崩溃：运行 `debug_tool_realtime_elements.py` 和 `_query_err.py` 寻找组件挂载失败的堆栈。

如果是业务逻辑 / 数据拉取异常：运行 `debug_tool_pre_caching_query_net.py`，传入发生异常的业务模块标识（如 /api/device/list），直接提取 Request/Response 负载进行接口契约校验。

5. 输出报告：整理定位到的根因（如：“由于 AntD Form 初始化 initialValues 类型与接口返回格式不一致导致组件白屏”），提供具体的代码修改路径，验证通过后执行 `stop_dev_env.py` 和 `runner.py --close` 清理现场。

按照以上架构设计进行重构，整个诊断链路将兼具低侵入性与高可追溯性。准备好进行具体的模块重构行动了吗？如果你需要，我们可以先从核心的 debug_tool_runner.py 生命周期管理逻辑开始梳理细节。

```

// End 方便阅读 ------------------------------------------------------------------------------------------

像上面这样的内容，如果完全由程序员手写，复杂度并不比手写代码低多少，工作效率大约只能提升 10% 左右。

但如果你足够了解 Markdown 格式，也熟悉豆包、千问、Gemini 等在线大模型产品的使用，可以通过套娃方式生成上述内容，那么在每次新功能、新模块的添加或模块改造上，**至少可以提升 30% - 60% 的工作效率**。

**划重点**：AI Coding 在处理复杂任务或添加新功能时，总会在一些细节或 bug 上有所缺失或不足。如果在修改细节和 bug 时还要从零开始构造复杂提示词，那么效率会大大降低。因此，程序需要自己的知识库，让 Vibe Coding 在修改细节和 bug 时也能得心应手。

## 【 3. 代码项目 - 初级知识库 Vibe Coding 】

1. 假设你已经通过一些技术和方法，构建好了自己项目工程的知识库文件，例如：

// Start 方便阅读 ------------------------------------------------------------------------------------------

```markdown

# CLAUDE.md - LsmHttpAgent 技术规范

## 1. 项目概述

LsmHttpAgent 是一个动态 HTTP 代理服务，支持配置多个代理节点，用于代理转发 Anthropic/Claude Code 请求和 OpenClaw (OpenAI协议) 请求到目标服务，并记录完整的请求响应日志到 MySQL 数据库，提供 Web 管理页面进行查询分析，方便调试和分析 AI 代理的工作流程。

## 2. 技术栈

| 类型 | 技术 |

| -------- | --------------------------------------------- |

| 语言 | Go 1.22+ |

| Web 框架 | 标准库 `net/http` |

| ORM | GORM 1.31.1 + MySQL Driver |

| 前端 | 原生 HTML + JavaScript（模板渲染 + API 驱动） |

| 架构 | 单一二进制，配置驱动，守护进程管理 |

## 3. 项目结构

### 3.1 模块划分

| 模块 | 文件 | 职责 |

| ------------------------- | --------------------------------- | --------------------------------------------- |

| **入口与进程管理** | `main.go` | 主程序入口、守护进程管理 |

| **配置管理** | `server_conf.go` | 配置文件读写、结构定义 |

| **日志系统** | `server_logger.go` | 日志初始化、轮转策略 |

| **代理引擎** | `server_http_agent_proxy.go` | 统一动态 HTTP 代理转发、HTTPS CONNECT 隧道 |

| **Web 服务** | `server_web.go` | Web 管理服务启动、路由注册 |

| **Web 页面-首页** | `server_web_home.go` | 首页导航模板 |

| **Web 页面-代理管理** | `server_web_http_agent_manage.go` | 代理节点增删改查管理页面 |

| **Web 页面-日志查询** | `server_web_chat_analysis.go` | 请求日志查询分析主框架 |

| **Web 页面-日志列表** | `server_web_chat_page.go` | 请求日志列表页模板（纯静态 + JS 渲染） |

| **Web 页面-日志详情** | `server_web_chat_detail.go` | 单条记录详情页模板（record-item 布局） |

| **Web 页面-统计分析** | `server_web_chat_total.go` | 时间段统计、协议分析统计页面 |

| **Web 页面-Session 分析** | `server_web_chat_session.go` | 一次对话框多轮对话 Session 分析 |

| **Web 页面-Task 分析** | `server_web_chat_task.go` | 每次独立对话任务分析 |

| **Web 工具** | `server_web_chat_script.go` | 共享 JS 工具函数（JSON 美化、SSE 解析、全屏） |

| **Web 通用** | `server_web_common.go` | Web 模板通用辅助函数 |

| **数据层-连接** | `mysql_connect.go` | MySQL 数据库连接初始化 |

| **数据层-代理配置** | `mysql_http_agent_manage.go` | 代理服务配置 CRUD |

| **数据层-模型** | `mysql_http_agent_model.go` | 代理服务通用模型定义 |

| **数据层-分表引擎** | `mysql_http_agent_sub_table.go` | 哈希分表存储引擎 |

| **数据层-分析查询** | `mysql_http_agent_analysis.go` | Session/Task 统计分析查询 |

| **测试** | `unit_test.go` | 单元测试 |

### 3.2 文件清单

````plaintext

LsmHttpAgent/

├── CLAUDE.md # 本技术规范文件

├── MEMORY.md # 项目记忆文件

├── README.md # 项目说明文档

├── LsmHttpAgent.conf # JSON 配置文件

├── build_deploy.sh # 编译部署脚本

├── main.go # 主程序入口 + 守护进程管理

├── server_conf.go # 配置文件读写管理

├── server_logger.go # 日志工具函数（轮转、初始化）

├── server_web.go # Web 管理服务启动

├── server_web_home.go # 首页模板

├── server_http_agent_proxy.go # 统一动态 HTTP 代理引擎

├── server_web_http_agent_manage.go # Web 动态代理管理页面

├── server_web_chat_analysis.go # 统一请求日志查询分析页面

├── server_web_chat_page.go # 请求日志列表页模板

├── server_web_chat_detail.go # 请求日志详情页模板

├── server_web_chat_total.go # 统计页面（时间段、协议分析统计）

├── server_web_chat_session.go # Session 分析页面

├── server_web_chat_task.go # Task 分析页面

├── server_web_chat_script.go # 共享 JS 工具函数

├── server_web_common.go # Web 模板通用辅助函数

├── mysql_connect.go # MySQL 数据库连接初始化

├── mysql_http_agent_manage.go # 代理服务管理数据层

├── mysql_http_agent_model.go # 代理服务通用模型

├── mysql_http_agent_sub_table.go # 哈希分表存储引擎

├── mysql_http_agent_analysis.go # Session/Task 分析数据库查询层

├── unit_test.go # 单元测试

└── bin/

└── LsmHttpAgent # 编译后的二进制文件

````

### 3.3 代码行数规范检查

> **强制要求**: 任何 Go 源文件代码行数不得超过 **1100 行**。

| 文件 | 行数 | 状态 |

| --------------------------------- | ---- | ---- |

| `main.go` | 534 | ✅ |

| `server_conf.go` | 270 | ✅ |

| `server_logger.go` | 120 | ✅ |

| `server_web.go` | 27 | ✅ |

| `server_web_home.go` | 200 | ✅ |

| `server_http_agent_proxy.go` | 356 | ✅ |

| `server_web_http_agent_manage.go` | 499 | ✅ |

| `server_web_chat_analysis.go` | 217 | ✅ |

| `server_web_chat_page.go` | 785 | ✅ |

| `server_web_chat_detail.go` | 314 | ✅ |

| `server_web_chat_total.go` | ~512 | ✅ |

| `server_web_chat_script.go` | 224 | ✅ |

| `server_web_common.go` | 46 | ✅ |

| `mysql_connect.go` | 64 | ✅ |

| `mysql_http_agent_manage.go` | 226 | ✅ |

| `mysql_http_agent_model.go` | 56 | ✅ |

| `mysql_http_agent_sub_table.go` | ~513 | ✅ |

| `unit_test.go` | 172 | ✅ |

**拆分原则**: 按功能模块拆分，高内聚低耦合；推荐单文件控制在 500-800 行以内。

## 4. 编码规范

### 4.1 Go 编码规范

1. **格式化**: 必须使用 `gofmt` 或 `goimports` 格式化代码

2. **错误处理**: 必须进行严密的错误处理，不允许使用 `_` 忽略关键错误

3. **变量命名**: 使用驼峰命名法，导出变量首字母大写，私有变量小写

4. **注释**: 每个导出函数必须有注释，复杂逻辑需要注释说明

5. **导入分组**: 标准库分组，第三方分组，本地模块分组

### 4.2 错误处理示例

````go

// 正确做法：检查并处理错误

if err != nil {

logger.Printf("[ERROR] Failed to do something: %v", err)

return err

}

// 错误做法：忽略关键错误

// result, _ := SomeFunction() // 禁止这样做

````

### 4.3 前端路径规范

> **强制要求**: Web 页面中的所有链接、表单 action、JS fetch 请求必须使用**相对路径**，禁止使用以 `/` 开头的绝对路径。

- **原因**: 代理服务可能监听与 Web 管理相同的域名或端口，绝对路径的请求可能被代理服务拦截转发，导致返回 HTML 而非预期 JSON

- 从 `/ChatManage` 返回首页：使用 `href="../"` 而非 `href="/"`

- 从 `/ChatManage` 调用 API：使用 `fetch('../api/agent/add')` 而非 `fetch('/api/agent/add')`

- 在同一 `/ChatAnalysis` 页面内跳转：使用 `href="./ChatAnalysis?..."` 而非 `href="/ChatAnalysis?..."`

## 5. 功能模块

### 5.1 核心功能

| 功能 | 说明 |

| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |

| **配置文件读取** | 读取 `LsmHttpAgent.conf`，包含 webListenPort、logFileURL、logMaxSizeMB、tableMaxRows、DBMysqlSubTableNumber、DBMysql 等配置 |

| **守护进程管理** | `-d` 守护进程模式启动（自动停止旧进程）；`-u` 停止守护进程；支持 `nohup` 直接启动调试 |

| **动态 HTTP 代理透传** | 多代理节点独立监听；完整透传 HTTP 方法、头信息、请求体；正确处理 URL 拼接；支持 SSE 流式响应透传；支持 HTTPS CONNECT 隧道代理 |

| **MySQL 数据存储** | 完整保存请求响应到统一哈希分表 `TAgentHttpTransactionDataItem_XX`；按 `fnv32a(serviceName) % subTableNumber` 路由；支持 Base64 编码存储二进制数据 |

| **日志轮转** | 超过配置大小自动轮转备份，命名格式 `LsmHttpAgent.1.log`；日志只输出简要信息，详细数据保存到数据库 |

### 5.2 Web 管理功能

| 页面/功能 | 说明 |

| --------------------------------------- | --------------------------------------------------------------------- |

| **首页** | 导航入口，进入代理节点管理 |

| **代理节点管理** `/ChatManage` | 动态增删改查代理服务节点（名称、监听端口、目标URL、协议类型） |

| **日志查询** `/ChatAnalysis` | 纯静态页面，JS 调用 API 渲染；支持分页、URL 模糊搜索、方法/状态码过滤 |

| **单条详情** `/ChatAnalysis?id=xxx` | 与列表页一致的 `record-item` 卡片布局 |

| **统计分析** `/ChatAnalysisTotal` | 按时间段、协议分析统计；支持 7/14/30/60/90 天时间跨度 |

| **Session 分析** `/ChatAnalysisSession` | 分析一次对话框打开期间的多轮对话；支持 1/3/7/14/30/60/90 天 |

| **Task 分析** `/ChatAnalysisTask` | 分析每次独立对话任务；支持 1/3/7/14/30/60/90 天 |

### 5.3 日志查询特性

- 分页支持 (1/2/5/10 条每页)

- 按 ID 倒序显示最新对话

- URL 模糊搜索过滤

- 请求方法下拉过滤

- 响应状态下拉过滤（含 429 等 20+ 状态码）

- 请求头/请求内容/响应头/响应内容全部支持折叠展开，默认折叠

- 请求体/响应体 JSON 美化切换（支持 `{}` 块点击折叠）

- 响应体 SSE 流式解析展示

- 内容区域全屏查看（按 Esc 或点击按钮退出，兼容手机 Chrome）

- 智能分页: 超过 10 页显示 `1 2 3 4 5 ... ... 尾5页`

- 移动端友好设计

### 5.4 Session / Task 定义

| 概念 | 定义 |

| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |

| **Session** | Claude Code CLI 打开一次对话框为一个 Session。同一 `remote_addr` 的连续请求，时间间隔 < 5 分钟属于同一 Session |

| **Task** | 在 Session 内，每和 Claude 对话一次为一个 Task。判定规则：POST 请求到 `/messages` (Anthropic) 或 `/chat/completions` (OpenAI) 端点 |

### 5.5 协议分析统计维度

基于最近 500 条有请求体的记录，解码 base64 后解析 JSON 进行统计：

- 模型分布、流式/非流式占比、SystemPrompt 使用率、工具调用率、多轮对话占比

- HTTP 方法分布、URL 调用模式 Top 10、响应状态分布

- 平均/最小/最大响应时间、平均请求/响应大小

## 6. 服务端点

### 6.1 动态代理服务（按配置端口）

| 端点 | 功能 |

| ---------- | ------------------------------ |

| `/` | 统一代理请求转发到对应目标地址 |

| `/CONNECT` | HTTPS CONNECT 隧道代理 |

### 6.2 Web 管理页面（端口 9101）

| 端点 | 类型 | 功能 |

| ------------------------------- | ---- | ----------------------------- |

| `/` | 页面 | 首页导航 |

| `/ChatManage` | 页面 | 动态代理节点管理 |

| `/ChatAnalysis` | 页面 | 请求日志查询分析页面 |

| `/ChatAnalysis?id=xxx` | 页面 | 单条记录详情页 |

| `/ChatAnalysisInterface` | API | 请求日志查询 API（POST JSON） |

| `/ChatAnalysisTotal` | 页面 | 代理服务统计页面 |

| `/ChatAnalysisTotalInterface` | API | 统计数据查询 API（POST JSON） |

| `/ChatAnalysisSession` | 页面 | Session 分析页面 |

| `/ChatAnalysisSessionInterface` | API | Session 分析 API（POST JSON） |

| `/ChatAnalysisTask` | 页面 | Task 分析页面 |

| `/ChatAnalysisTaskInterface` | API | Task 分析 API（POST JSON） |

## 7. 数据库表结构

### 7.1 代理服务配置表 `TAgentServiceInfoItem`

| 字段 | 类型 | 说明 |

| ----------------------------- | ------------ | -------------------------------- |

| `id` | 自增主键 | |

| `agent_service_name` | string, 唯一 | 代理服务名称（如 "Claude Code"） |

| `agent_service_description` | string | 描述 |

| `agent_src_protocol_type` | string | 源协议类型 (Anthropic/OpenAI) |

| `agent_dst_protocol_type` | string | 目标协议类型 (Anthropic/OpenAI) |

| `agent_service_listen_port` | int | 本地监听端口 |

| `agent_service_dst_agent_url` | string | 目标代理地址 |

| `created_at` | datetime | 创建时间 |

| `updated_at` | datetime | 更新时间 |

### 7.2 统一哈希分表 `TAgentHttpTransactionDataItem_XX`

| 字段 | 类型 | 说明 |

| ------------------------- | ------------ | ------------------------------ |

| `id` | 自增主键 | |

| `agent_service_name` | string, 索引 | 代理服务名称（哈希分表路由键） |

| `agent_src_protocol_type` | string | 源协议类型 |

| `agent_dst_protocol_type` | string | 目标协议类型 |

| `request_method` | string | 请求方法 |

| `request_url` | string, 索引 | 完整请求 URL |

| `request_remote_addr` | string, 索引 | 客户端地址 |

| `request_content_length` | int | 请求内容长度 |

| `request_headers` | text | 请求头（文本格式） |

| `request_body` | longtext | 请求 Body |

| `response_status` | int, 索引 | 响应状态 |

| `response_content_length` | int | 响应内容长度 |

| `response_headers` | text | 响应头（文本格式） |

| `response_body` | longtext | 响应 Body |

| `elapsed_ms` | int | 处理耗时（毫秒） |

| `created_at` | datetime | 创建时间 |

| `updated_at` | datetime | 更新时间 |

## 8. 编译与部署

### 8.1 编译要求

- 使用 Go 模块 (`go mod tidy`)

- 输出二进制到 `./bin/LsmHttpAgent`

- 编译前检查代码行数，确保不超过 1100 行限制

- 编译时注入 buildTime 变量：`-ldflags "-X main.buildTime=$BUILD_TIME"`

### 8.2 命令行参数

| 参数 | 说明 |

| ---- | ------------------------------------------- |

| `-d` | 守护进程模式启动 |

| `-u` | 停止守护进程 |

| `-c` | 配置文件路径（默认: `./LsmHttpAgent.conf`） |

### 8.3 一键编译部署

````bash

./build_deploy.sh

````

脚本步骤：

1. 编译当前程序（自动注入编译时间）

2. 复制二进制到 `./bin/LsmHttpAgent` 和 `./LsmHttpAgent`

3. 停止旧进程（自动检测 launchd / systemd / nohup 方式）

4. 启动新实例

5. 验证 Web 服务是否正常（HTTP 200）

**跨平台兼容**:

- macOS: `launchd` + `PlistBuddy` + `lsof`

- Linux: `systemd` (如果配置了) / `nohup` + `ss`/`netstat`

## 9. 运维规范

### 9.1 服务重启规则

> **重要**: LsmHttpAgent 是 Claude Code 和 OpenClaw 的网络代理依赖。直接重启服务会导致正在进行的 AI 对话、代码编辑等操作中断。

#### 核心原则：动态代理节点零重启管理

- 新增/修改/删除代理节点：访问 `http://localhost:9101/ChatManage`

- 所有代理节点变更**无需重启服务**，实时生效

- 禁止为了修改代理端口或目标地址而重启整个服务

#### 代码升级/二进制替换重启流程

必须使用**滚动重启**策略：

````bash

# 步骤 1: 用 nohup 启动新实例（不杀死旧进程）

nohup ./bin/LsmHttpAgent > lsm_new.log 2>&1 &

# 步骤 2: 验证新实例正常

curl -I http://localhost:9101/

# 步骤 3: 确认新实例正常后，再停止旧实例

./bin/LsmHttpAgent -u

````

**禁止的操作**:

- ❌ 使用 `./bin/LsmHttpAgent -d` 直接重启（会自动 kill 旧进程）

- ❌ 在 Claude Code / OpenClaw 正在长对话或流式响应过程中重启

- ❌ 不验证新实例就停止旧实例

#### 紧急情况回滚

如果新实例启动失败：

````bash

# 旧实例仍在运行，直接终止失败的新实例

kill $(pgrep -f "LsmHttpAgent" | tail -1)

````

#### 最佳实践

- **低峰期操作**: 选择 AI 工具空闲时段进行必须的重启

- **提前通知**: 重启前确保团队成员知晓

- **配置变更优先用 Web**: 99% 的配置变更通过 Web 管理页面完成，无需重启

- **数据库持久化**: 代理节点配置保存在 MySQL，重启后自动恢复

## 10. 功能扩展原则

1. 评估当前文件行数，如果接近 1100 行，先拆分模块

2. 按照功能职责拆分到不同的包文件

3. 保持每个文件行数在限制以内

4. 更新本文档记录项目结构变化

```

// End 方便阅读 ------------------------------------------------------------------------------------------

上面是一个标准项目的 `AGENTS.md` 或 `CLAUDE.md` 知识库文档。

2. 有了这样一个标准化的知识库文件，就可以通过发送一些简单指令，让 AI 自动化编程工具运行起来，完成开发工作、修改 bug、优化细节等。以下是简单的指令示例。

下面是一个 OpenClaw 简单的指令：

```markdown

# OpenClaw 自动修改代码，自动编译，自动运行验证处理

1. 设置路径 `/XXXXXXXXXXXXXXXXXXXXXX/LsmHttpAgent/` 为当前工作目录；注意不要修改当前工程代码，这是 Claude Code 的工作目录，只能读取。

2. 读取配置文件 `LsmHttpAgent.conf`，获取数据库相关的地址、账号、密码和默认数据库名称。

3. 读取 `mysql_http_agent_model.go` 代码文件，获取数据库表 `TAgentServiceInfoItem` 和 `TAgentHttpTransactionDataItem` 完整的 gorm 定义——代理服务信息内容列表和存储每次 HTTP 代理请求和响应信息。

4. 创建子目录 `AnthropicAnalysis` 可以使用 python 代码实现，读取出关于 `Anthropic` 相关主要数据，注意 响应状态 为 200 的数据；

5. 分析 `Anthropic` 协议中关于每次 Session 和每次人工提示词任务的，区分，总结出 `Anthropic` 协议的核心规律，输出到 `AnthropicAnalysis/OutputAnalysis.md` 文件中。

```

下面是一个 Claude Code 简单的指令：

```markdown

# Claude Code 自动修改代码，自动编译，自动运行验证处理

1. 页面URL `/ChatTotal` 更改为 `/ChatAnalysisTotal` 显示的统计信息，相关的页面跳转和连接，也一起修改。

2. 新增2个页面 `/ChatAnalysisSession` 和 `/ChatAnalysisTask` 主要用于分析下面自定义的2个概念：

Claude Code CLI 打开一次对话框，用户可以输入多次对话任务，这一个打开为一个 `Session`

Claude Code CLI 打开一次对话框，为一个 `Session`，每和 Claude 对话一次，定义为一个 `Task`

3. 根据当前数据库 分析 `Anthropic` 协议，`Session`概念，OpenClaw 输出为 `AnthropicAnalysis/SessionAnalysis.md` 这个文件。

4. 根据当前数据库 分析 `Anthropic` 协议，`Task`概念，OpenClaw 输出为 `AnthropicAnalysis/TaskAnalysis.md` 这个文件。

5. 根据当前数据库 分析 `OpenAI` 协议，`Session`概念，OpenClaw 输出为 `OpenAIAnalysis/OpenClaw_SessionAnalysis.md` 这个文件。

6. 根据当前数据库 分析 `OpenAI` 协议，`Task`概念，OpenClaw 输出为 `OpenAIAnalysis/OpenClaw_TaskAnalysis.md` 这个文件。

7. 新增的 go 代码文件，注意命名规则，注意代码文件的拆分，要符合当前工程的规律和规则。

8. 功能测试通过后，更新 `README.md`、`CLAUDE.md` 文件，方便 Claude 后续自动加载使用。

```

3. 因此，通过一些简单的格式指令，就可以快速完成从复杂任务处理 → 简单任务 → 细节调优 → bug 修改的全链路工作，出色地完成各个阶段的任务处理。全程使用 Vibe Coding，也可以实现超大规模代码工程的开发。

## 【 4. 中级知识库形态 】

1. 上面阐述了初级知识库的形态，主要还是由程序员设计实现和使用，它需要具备编程技能的人来操作，完成相关功能开发、细节优化和 bug 修改。要想完全脱离程序员，让产品、测试甚至销售人员也能自动修改程序，就不仅仅是构建自己项目代码的知识库那么简单了，当然知识库的细节描述也是必不可少的。

2. 如果要让非开发人员也能驾驭程序代码开发，就需要引入更多的工具、更细节的描述、更完整的闭环流程处理，以及相关的配套工具开发。