# LingYuCoder

**Repository Path**: 203014/ling-yu-coder

## Basic Information

- **Project Name**: LingYuCoder
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-26
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 灵羽（Ling-Yu-Coder）

基于 **Electron + CodeMirror** 搭建的多 Agent 智能编码桌面应用原型，内置从需求澄清到文档生成的完整流水线。

## 已实现模块

- ✅ Clarifier Agent：拆解用户目标与约束。
- ✅ Retriever Agent：结合长期记忆提取上下文。
- ✅ Plan Agent：生成执行计划。
- ✅ Act Agent：执行代码改写动作。
- ✅ Compiler Agent（语法检查）：使用 `acorn` 做 JS 语法检测。
- ✅ Test/Runtime Agent：通过 Node `vm` 执行代码并采集日志。
- ✅ Approval Gate（确认门禁）：修改前弹窗审批。
- ✅ Memory Module（长期记忆）：持久化到 Electron `userData/memory.json`。
- ✅ Environment Inspector：采集 Node/Electron/平台信息。
- ✅ Codebase Modifier（多文件协调）：批量写入目标文件。
- ✅ Documentation Writer：生成任务执行文档。
- ✅ LLM Manage（支持在线+本地）：可在在线/本地 provider 间切换。
- ✅ LLM 健康 IPC：主进程已提供 `llm:health` / `llm:probe`，可用于 UI 仪表盘拉取 provider 状态与熔断指标。

## 模块调度协议与标准规范

已补充完整规范文档（包含：统一消息信封、状态机、错误码、模块 MVP 契约、可观测性与安全基线）：

- 👉 `docs/dispatch-protocol.md`
- 👉 `docs/implementation-status.md`

### 本次新增的关键规范点

1. **统一消息协议**：所有模块统一 `protocolVersion/traceId/requestId/stage/payload/meta`。
2. **标准生命周期**：`INIT -> ENV_CHECK -> ... -> END`，并明确失败回流机制。
3. **错误码体系**：覆盖审批拒绝、编译失败、运行失败、IO/Provider 异常等。
4. **模块最小实现清单（MVP）**：每个模块都定义了职责、最小输入输出、实现要求。
5. **安全基线**：目录越界防护、沙箱执行、最小权限 IPC。

## 快速开始

```bash
npm install
npm run start
npm test
npm run test:e2e
npm run test:e2e:smoke
npm run test:e2e:full
```

> `npm run test:e2e` 当前包含三类 Electron E2E：UI 主流程（点击运行并生成文档）、审批拒绝分支验证，以及预加载 `lingYuAPI` 的真实进程级 IPC 桥接验证（环境检测/记忆读写/运行沙箱含超时分支/审批门禁/LLM 健康探测/代码修改冲突分支）。

项目已提供 GitHub Actions CI（`.github/workflows/ci.yml`）：`push/PR` 执行 `npm test + E2E smoke`；`schedule/workflow_dispatch` 以 matrix 执行 `smoke/full`，并生成 E2E 聚合报告（`GITHUB_STEP_SUMMARY`）。
nightly full 失败时会触发 quarantine rerun，并把失败用例写入 flake history（按测试名统计，30 天窗口 + 按天衰减 score）用于趋势观察。
CI 已把 flake 趋势接入告警门槛：score 超过 warning 阈值会标黄，超过 blocking 阈值会直接让 nightly 报警并失败；阈值支持按分支默认值、仓库变量覆盖与维护窗口 warn-only 模式。
flake 报表中已追加维护窗口命中率（silentWindowHits / gateRuns），用于评估是否需要动态调窗。
flake 报表同时输出按分支拆分面板与最近 10 次时间线（branch/maxScore/silentWindow），并导出 Prometheus 指标（`reports/flake-metrics.prom`）以接入 Grafana。
flake gate 还会计算 7/30 窗口 SLO burn-rate（以 warn 阈值为 breach 基线），并按 burn-rate 触发 on-call 升级：primary/secondary 两级值班路由。

UI 已接入 LLM 健康仪表盘：展示 active provider、online/local 状态、健康指标，并在熔断/退化/探测成功率下降时写入告警列表。
已支持外部告警 Webhook MVP：在 UI 录入 webhook URL/Secret 后，健康告警会通过 `alert:webhook` 发送（支持 `v2/v1` 协商、tenant/key-id 头、内置 5 分钟同类告警去重，失败自动重试 + 失败落盘队列）。
`docs/dispatch-protocol.md` 已补充多租户密钥轮换与 key-id 协商规范、接收端验签示例（Node/Express）及安全基线（IP 白名单 + nonce/timestamp 重放防护）。
新增双向 ACK 与死信重放接口：`alert:webhook:ack`、`alert:deadletter:list`、`alert:deadletter:replay`，便于告警网关补偿与人工回放。

## 项目结构

```text
.
├─ docs
│  └─ dispatch-protocol.md     # 模块调度协议与实现规范
├─ main.js                     # Electron 主进程 + IPC
├─ preload.js                  # 安全桥接 API
├─ src
│  ├─ index.html               # 主界面
│  ├─ styles.css               # 样式
│  ├─ renderer.js              # Agent 编排与交互
│  ├─ agents                   # 各 Agent 实现
│  └─ core                     # Memory/Gate/Inspector/Modifier
└─ package.json
```

## 工作流

1. Environment Inspector 检测当前运行环境。
2. Clarifier / Retriever / Plan 生成任务上下文与计划。
3. Approval Gate 确认后，Act Agent 执行变更。
4. Compiler + Runtime 执行质量闸门（支持失败后自动修复重试）。
5. Documentation Writer 输出结果文档。
6. Memory Module 保存关键摘要（支持 TTL/数量裁剪/过期归档），Codebase Modifier 以 transactional + 冲突检测 + patch-level 合并方式回写产物。
# Codex-style usage

See `docs/codex-usage-manual.md` for Agent/Plan/Ask modes, access modes, LM Studio setup, real file-write flow, and troubleshooting.