# Stylotrace

> Stylotrace = style + trace：从你的修改轨迹里学出你的文风。

**给你的 AI Agent 装一个“会写、还会学你风格”的写作子 agent。**

Stylotrace 是一个深度协作写作 Agent，做成 skill / MCP / CLI / DSH 插件，装进你正在用的
Codex、Claude Code、OpenCode、DeepSeek Harness、Cursor、Windsurf 等主流 agent 宿主，随叫随到。
它只负责“写作”这一件事，但在这件事里主导全程：先读懂你想写什么、从你的每一次修改里学会你的
文风，再陪你走完 澄清 → 大纲 → 写作 → 审计 → 交付。

> 通用写作的下限由模型能力决定，上限由系统对“作者”的理解决定。

## 它能替你做什么

- **从你的修改里，学会你的文风**（改迹调制）：你每一次亲手改稿（原文 → 改后 → 意图）都是最高密度的
  风格信号。几十次修改后，它学会你的断句、你的口头禅、你的收尾方式——写出来的是“你写的”，
  不是一篇通用范文。
- **一条完整写作工作流**：说清要写什么 → 学会你的风格 → 出大纲 → 逐段写 → 复阅修订 → 反 AI 审计 →
  读者群像 → 交付导出。你只回答该你决定的问题，其余它自己推进。
- **项目自动提炼成文章**（synthesize）：给一个项目目录（缺省当前目录），自动收集 README / 文档 /
  提交记录 / 上下文，提炼成实验报告、产品介绍、技术综述、README、技术博客——面向“做完了东西不想写”的你。
- **告别 AI 味**：人类化指数打分（0–100），套话、重复比喻、“首先/其次/最后”式过渡一条条揪出来，
  不达标一键按你的风格重写复检。

## 装进你的 Agent

```bash
# DeepSeek Harness（DSH）—— 43 个 MCP 写作工具
dsh plugin --profile web add dsh-plugin-stylotrace

# Codex / Claude Code / OpenCode / Cursor / Windsurf（skill + MCP + CLI）
curl -fsSL https://raw.githubusercontent.com/zhangyoufu-123/stylotrace/main/install.sh | bash -s -- --all
```

装完在新对话里直接说「写一篇关于故乡的散文，要有我的风格」即可。跨宿主接入片段与规则适配见
[adapters/README.md](adapters/README.md)。

## 30 秒用法

```text
你说：帮我把这段周报改得像我写的，太官方了
  ↓  它先读懂你的写作风格（从你贴过的旧稿 / 亲手改过的句子 / 每轮对话里学）
  ↓  给你 3 个候选改写，并说清“为什么这么改”
  ↓  你选一个，或再说一句“结尾再收一点”——它吸收进你的风格档案，越用越像你
```

同一个内核也覆盖长文：议论文、散文、演讲稿、学术论文、公文、小说、长文系列，20+ 文体；
翻译走“先懂原意、再翻译、再回译校验”的闭环。所有能力在 agent 内以工具形式暴露，
宿主 / 上游 agent 可在任意一步插进来，也可随时取走半成品。

## 本地 Web 写作台（可选）

同一引擎也打包成一个浏览器写作台（BYOK，自带 Key）：对话 + 实时大纲 + 手写区 +
审计页 + 作品库，适合不想用命令行、想看得见过程的场景。它在插件形态之外独立可选，
不影响 agent 内使用。

```bash
cd web && npm start        # → http://localhost:5177
cd web && npm run mock     # 离线 mock 模式，无 API 也能体验
```

Web 只是同一内核的另一种皮，不是另一个产品。

## 为什么会有它

大多数 AI 写作工具只做一件事：你把题目丢给它，它把文章吐给你。结果“像模像样，却一眼假”——
结构工整、辞藻平滑，就是没有人味。问题不在模型，在于它不认识你：不知道你读过什么、在意什么、
句子习惯怎么断、情绪习惯怎么收。它写的是“一篇好文章”，不是“你写的文章”。

所以我们换了思路：先花时间了解作者，再动笔。风格不是套模板，是从你写过的文、读过的书、
反复改过的地方里提取出来的。

## 它怎么做到“写得像我”

1. **四层风格向量**：连续向量（方向差）+ 动态维度 + 语言新鲜度 + 亲手修改记录；你随口一句
   “太文艺了”“结尾收一点”，都会被吸收进档案。
2. **改迹调制**：把每一次修改当成偏好标注，学习十三维外层调制器权重；每节并行生成候选、
   评分选优，并给出“为什么选它”的得分分解。
3. **改迹变换 + 拟改层**：从编辑对学“你会新增/删除什么”，选优后复现你的改法——删掉你会删的
   连接词、把抽象句改具体。
4. **小样本冷启动**：改过一句话就能开始被“读懂”，不用攒一堆语料。
5. **思想脉络**：追踪你发言里的“主张 → 前提 → 推理 → 理论来源”，顺着你的思路做一步概括、再请确认。
6. **反 AI 痕迹硬规则**：黑名单套话、重复比喻、句式复用自动修订，交付前人类化指标把关。

## 最近的关键升级

- **改迹调制（v1.0）**：作者每次修改即偏好标注，几十次修改学到稳定的作者方向，逐维可消融、可解释。
- **词级文体计量**：功能词 + 标点节奏（Burrows Delta 思想）作个人模型，风格信号在“怎么断句、用哪些虚词”。
- **小样本冷启动**：个人语料阈值降到 1 条编辑对即启用对比解码。
- **极客模式 / 质量循环 / 项目提炼**：导演自动启动、少访谈；polish 质量门自动改到达标；
  synthesize 把项目提炼成文章。
- 更早的实时大纲、外溢优先、全流程互操作、批注闭环、姿态层诊断等见 [CHANGELOG.md](CHANGELOG.md)。

## 理论与证据

- [docs/THEORY.md](docs/THEORY.md)：Agent / 人工智能 / 数学 / 工程四维理论架构与竞品对照。
- [docs/UNIFIED-TOKEN-FRAMEWORK.md](docs/UNIFIED-TOKEN-FRAMEWORK.md)：统一 Token 对比框架的现状审计与升级路线。
- 风格向量与作者识别 / 续写实验脚本：`scripts/style-vectors.py` / `author-id.py` / `author-predict.py`。

## 文档

- [CSLA 认知运行时 · Source of Truth（先读这个）](docs/csla/00-SOURCE-OF-TRUTH.md)
- [使用手册（命令大全）](docs/GUIDE.md)
- [理论架构](docs/THEORY.md)
- [文档互通管线（全流程文件进出）](docs/INTEROP.md)
- [完整风格体系设计](docs/STYLE-SYSTEM.md)
- [外层调制器：把签名升级为可学习模型](docs/MODULATOR.md)

## 仓库结构

本仓库只保留产品本体：`agent/`（核心引擎）、`skills/`（可安装技能）、`web/`（可选本地写作台）、
`api/`（可选自部署 API）、`scripts/`（实验与工具）、`extras/dsh-plugin-stylotrace/`（DSH 插件）、
`install.sh`、`README.md`。论文与竞赛材料为个人成果，不随仓库发布（见 `.gitignore`）。

## 质量与可信

- **agent 40 个自动化测试文件全绿**：一次一问、实时大纲、字数达标、红队 8 文体 × 6 对抗输入、
  十种用户说法、12000 字长文端到端、回译校验、全格式导出，以及统一 Token 解码、改迹调制、
  神经风格编码、作者写作清单、姿态层细读前置、盲评统计等回归。
- **确定性兜底**：任何 LLM 或网络不可用时，流程降级但不崩溃。
- **密钥安全**：自动发现宿主配置的 API，绝不打印；提交前自动扫描密钥（CI 内置）。
- **不覆盖你的稿子**：任何文件被外部改过，它都会停下让路，绝不悄悄覆盖。

## 路线图

已落地：四层风格体系、改迹调制 V1.5（外层调制器，偏好对学十二维权重、增量在线更新）、
导演状态机与多 Agent 协作、真实 LLM 可靠性修复、翻译方法论、数学可视化、DSH 插件分发。
接下来：意图分流训练、状态向量化、V2 logprobs / V3 本地 DExperts 与激活转向、
第三方盲评样本收集、跨语言语料验证。