zhangyoufu-123 / stylotrace

Stylotrace

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

一个会先读懂你、再陪你写好的深度协作写作 Agent（v1.0）。

装上它之后，你不需要会写提示词——说出一个念头，剩下的澄清、大纲、成稿、修改、审计，它陪你走完。 装进 Codex / Claude Code / OpenCode 是写作合伙人；接进 Cursor / Windsurf / Claude Desktop / Hermes 等 任意 MCP 宿主是写作子 agent；在终端用 stylotrace agent 是独立导演。三种形态，同一个决策内核。

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

🔥 它能替你做什么（30 秒看懂）

• 学会同事 / 领导的写作风格 —— 把同事的周报、领导的邮件喂给它，它就学会对方的句式、用词与语气。下次汇报，由你署名，但"像你写的"。
• 学会任何人的风格 —— 偶像的专栏、喜欢的作家、行业 KOL：给几篇样本，蒸馏成可复用的"文风指纹"，一键把你的稿子改写成他的味儿。
• 做出了东西不想写报告？ —— 给它一个项目目录（缺省当前目录），自动提炼成实验报告 / 产品介绍 / 技术综述 / README / 技术博客，不用逐项交代要求。
• 告别 AI 味 —— 人类化指数打分（0-100）：黑名单套话、排比套路、"首先/其次/最后"式过渡，一条条给你揪出来；不达标一键按你的风格重写复检。
• 会越写越像你 —— 你每一次亲手修改都是训练信号。几十次修改后，它学会你的断句、你的口头禅、你的收尾方式。

装进 DeepSeek Harness（DSH）只需一条命令：

dsh plugin --profile web add dsh-plugin-stylotrace   # 43 个 MCP 写作工具

装进 Codex / Claude Code / OpenCode / Cursor / Windsurf 见下方「安装」。

跨宿主接入方式（skill / MCP / CLI 的配置片段与规则适配）见 adapters/README.md。

为什么会有它

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

所以我们换了个思路：先花时间了解作者，再动笔。

我们相信的四件事

一、风格不是模仿，是提取。 风格是"人天然的不规范表达，与完美表达之间的差异弥补"——这种差异不可预测、带着个人知识库里的 无限联想，正是"人味"的来源。Stylotrace 用四层表征持续追踪它：连续向量、动态维度、语言新鲜度 （不可预测性）、亲手修改记录（原文→改后→意图）。从你写过的文、读过的书、反复改过的地方 里提取，而不是套用名人的模板。

二、读过的书，是写作的土壤。 一个人的联想和理论，都来自他读过什么、经历过什么。Stylotrace 归纳式地收集你的知识：你提到一本 读过的书，它问一句"要我记进你的知识库吗"；你说想去某处，它记下来。写作用到时按主题调取、轮换 使用，绝不反复引用同一本让你起疑；你心里有个模糊想法，它还会主动递上一本相近的书，说清"这个 理论是什么、为什么适合你"。

三、AI 该有自己的生态位，而不是抢走整张桌子。 Stylotrace 只负责"写作"这一件事，但在这件事里它主导：问什么、何时写、缺什么数据，它自己决定； 需要查资料时自动排队请求，宿主或学术 Agent 检索回灌后自动补写缺口。编程、答疑等生态位外， 它完全让位，不和其他 Agent 打架。

四、机器翻译和机器写作一样，先懂人，再动手。 翻译以理解作者原意为第一标准：先读懂"作者想表达什么、什么语气、什么意象"，再动笔—— 达意优先于逐字；然后用"中译英→回译→信息点核对→风格对比"闭环校验，把翻译损耗和原文本身的 模糊区分开。

用它写一篇东西，会发生什么

你说：想写一篇关于××的散文
  ↓  它接住你的话，从思想里生长问题——一次只问一个，先懂你，再谈结构
  ↓  你的风格、知识、思想脉络（主张→前提→推理→理论来源），在对话中同步采集
  ↓  大纲成型（论文有论证链，小说有故事骨架与伏笔），你确认后才写
  ↓  逐节写作，每一节都带着"你的"风格画像，实时反馈风格脉搏
  ↓  复阅-修订：有没有偏题、衔接断没断、素材用够没
  ↓  反 AI 审计：套话、重复比喻、句式复用，按你的风格自动修掉
  ↓  8 位"第一读者"第一次读它的真实反应，交锋后把共识/争议交给你拍板
  ↓  交付：归档进个人写作库、蒸馏你的写作 skill、导出 Word / PDF / LaTeX

全程你只回答该你决定的问题，其余它自己推进。

它能写什么

• 为程序员而生：项目自动提炼（stylotrace synthesize）："我做出了东西，但不想自己写。" 给它一个项目目录（缺省当前目录），它自动收集 README / docs / package.json / 最近 git 提交 / 对话上下文 / 你的风格档案，提炼"你真正想表达什么"，按你的文风写成—— 实验报告、产品介绍、技术综述、README、技术博客；不确定事实标【待核实】，LLM 不可用自动降级。
• 议论文、散文、演讲稿：澄清 → 大纲 → 双风格写作 → 审计 → 读者群像，全流程自动。
• 学术论文：自带论证链（已知→缺口→张力→洞见→方法→证据→局限），逐节检查"论点有没有证据、 证据有没有推理桥"，自动生成参考文献草稿。
• 公文、投标书、申报书：20+ 文体范式，党政机关公文按 GB/T 9704-2012 国标排版导出。
• 小说、推理小说：角色档案 + 写作前"角色预演"（让角色自己决定怎么想、怎么说、怎么做）， 伏笔自动记账、跨章回收校验，故事像是自己长出来的。
• 长文、系列文：卷级大纲分卷展示，交付沉淀"文章圣经"，续写自动保持一致。
• 翻译与回译校验：原意优先翻译 + 回译校验闭环（信息不丢、风格可测）。
• 任何文体：扩写、缩写、润色、古文风、脱敏改写；版本可回滚；导出 docx / pdf / html / 字幕 / LaTeX。

不只是程序员：小说家、学生、自媒体、任何"要认真写"的人，它都陪你——同一套引擎， 文体与自由度都交给它自己判断，硬编码最少、AI 主导最多（导演状态机由 LLM 自主决策下一步， 人只在真正的决策点拍板）。

最近的关键升级

• 改迹调制（v1.0）：把作者每次亲手修改（原文→改后→意图）当作偏好标注，学习十三维 外层调制器权重；写作每节并行生成候选、评分选优，并给出"为什么选它"的得分分解与人话理由。 几十次修改即可学到稳定的作者方向。
• 词级文体计量（v1.0）：功能词 + 标点节奏（Burrows Delta 思想）替代字符 n-gram 作个人 模型，作者识别从 46% 提到 76%——风格信号在"怎么断句、用什么虚词"，不在内容实词。
• 改迹变换 + 拟改层（v1.0）：从编辑对学"作者新增/删除什么"（第 13 维），并在选优后 复现作者的改法——删掉他会删的连接词/AI 腔并断句，再用他的编辑对做 few-shot 把抽象句 改具体。从"打分排序"升级为"选优 + 拟改"。
• 小样本冷启动（v1.0）：个人语料阈值从 200 字符降到 1 条编辑对即启用对比解码， 新用户改过一句话就能开始被"读懂"。
• 评测与可靠性（v1.0）：调制器消融（学习权重 > 默认权重、逐维归因）、配对置换检验、 真实 JS 签名作者识别、以及覆盖空/畸形/对抗输入的红队测试——任何输入都不崩溃、优雅降级。
• 更早的实时大纲、联网查验、外溢优先、全流程互操作、批注闭环、姿态层诊断、L3 作者写作清单等 见 CHANGELOG.md。

它怎么做到"写得像我"

1. 四层风格向量：连续向量（方向差）+ 动态维度 + 语言新鲜度 + 亲手修改记录；"太文艺了""结尾 收一点"这类修改意见都会被吸收进档案与向量。
2. 双风格模型：你想写的风格，和你想听的风格，是两回事——分开采集、分开注入。
3. 人物风格肖像：把知识库、旧作、修改记录侧写成一幅"写作人格画像"，随时可查（stylotrace persona）。
4. 思想脉络：追踪你发言里的主张-前提-推理-理论来源，AI 顺着你的理论做一步概括、再请确认—— 它知道 1+1 为什么等于 2，而不是只记一个 2。
5. 提问主次：先问为什么现在想写、心里憋着的那句话、怎么展开；素材、论点次之；字数等规划参数 最后从内容反推。问什么由 LLM 结合对话自主判断，蓝图状态只是清单，代码只防死循环。
6. 反 AI 痕迹硬规则：黑名单套话、重复比喻、句式复用自动修订，交付前人类化指标把关 （句长标准差/段落变异/句首去重/词汇 TTR）。

Web 写作工作台（伴随式）

web/ 把同一核心包装成浏览器里的完整写作台：对话、实时大纲（列表/图谱双视图、点击定位草稿）、 写作手写区（选区 AI 工具栏、3 候选改写卡、版本回滚、专注/并排模式）、实时洞察（字数进度、 风格脉搏、节奏曲线）、上下文面板（我的理解/素材/思想脉络/风格进度/RAG）、审计页（人类化指标、 伏笔回收时间线、回译校验）、作品库（按文体分类 + 蒸馏个人 skill + 多作品指标对比）。

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

Web 端采用 BYOK（自带 Key），形态借鉴 DeepSeek Harness 的「下载到本地 + 浏览器里自己填 Key」： 右上角点「🔑 模型与 API Key」，选服务商（DeepSeek / OpenAI / OpenRouter / Moonshot / Qwen / GLM / Gemini / 自定义 OpenAI 兼容网关）→ 粘 Key → 选模型 → 保存。Key 只写进本机浏览器的 localStorage，每次请求以 Authorization: Bearer 直达 LLM，服务端不留存、不代付，并按 key 隔离会话。 首次打开若本机和服务端都没有 Key，会主动弹一次引导。留空 Key 时回退到服务端环境变量里的凭据 （适合本地自用）；对外部署时建议不要配 STYLOTRACE_LLM_API_KEY，强制用户自带 key。

公开 API（FastAPI + BYOK）

api/ 把同一引擎包装成可自部署、可对外调用的 HTTP API。核心是 BYOK（Bring Your Own Key）： 用户带自己的 LLM API Key 调用，服务端不存中心账号、不出任何 LLM 费用；同一个 key 既是身份 （区分会话）也是计费凭证（走这个 key 调 LLM）。自带一个浏览器聊天前端，也可直接用 curl 调用。

./run-api.sh                 # 一键启动 → http://localhost:8000
STYLOTRACE_MOCK_LLM=1 ./run-api.sh   # 离线冒烟

curl -X POST http://localhost:8000/v1/chat \
  -H "Authorization: Bearer sk-你的LLM密钥" \
  -H "Content-Type: application/json" \
  -d '{"message":"我想写一篇关于故乡的散文"}'

完整端点、账号模型与 Docker 部署见 api/README.md。

理论与证据

• docs/THEORY.md：Agent / 人工智能 / 数学 / 工程四维理论架构与竞品对照。
• docs/UNIFIED-TOKEN-FRAMEWORK.md：统一 Token 对比框架 （风格/知识/缺陷/阻抗在 token 概率空间融合）的现状审计与升级路线。
• 风格向量与作者识别/续写实验脚本：scripts/style-vectors.py / author-id.py / author-predict.py。

安装

curl -fsSL https://raw.githubusercontent.com/zhangyoufu-123/stylotrace/main/install.sh | bash -s -- --all

装完在新对话里直接说"写一篇关于××的散文，要有我的风格"即可。详细使用手册见 docs/GUIDE.md。一键安装三个安装点（全局 skill / 项目级 skill / 开发镜像）， 目录级生效、不碰其他项目。

装进 DeepSeek Harness（DSH 插件）

dsh plugin --profile web add dsh-plugin-stylotrace   # 43 个 MCP 写作工具
npx stylotrace-plugin install --all                  # 技能包 → DSH / Codex / Claude Code / OpenCode

插件包位于 extras/dsh-plugin-stylotrace/，安装后 DSH Agent 立即获得 mcp__stylotrace__* 全流程写作工具（澄清/大纲/写作/红队/读者群像/定点修改/风格学习/ 项目提炼 synthesize / 质量循环 polish），Web 端还有选中批注与文件内嵌预览（Codex 式）， 并自动复用 DSH 的 $DSH_HOME/.credentials.yaml 凭据（STYLOTRACE_LLM_API_KEY 显式配置永远优先）。 详细说明见 extras/dsh-plugin-stylotrace/README.md。

文档

• 使用手册（命令大全）
• 理论架构
• 文档互通管线（全流程文件进出）
• 问询系统升级设计
• 完整风格体系设计：从表层指纹到深层选择模式（含解码期控制路线）
• 外层调制器：把签名升级为可学习模型（偏好对学权重，推理时调制）

仓库结构

本仓库只保留产品本体：agent/（核心引擎）、skills/（可安装技能）、web/（写作工作台）、 scripts/（实验与工具）、install.sh、README.md；论文与竞赛材料为个人成果，不随仓库发布 （见 .gitignore）。

• Web 人机交互规划
• Web 接口自检报告
• Web 演示版部署指南
• 产品设计文档

质量与可信

• agent 24 套 + web 11 套自动化 QA 全绿：一次一问、实时大纲、字数达标、红队 8 文体 × 6 对抗输入、 十种用户说法、风格差异对照、12000 字长文端到端、回译校验、全格式导出、前端接线静态检查， 以及统一 Token 解码（个人模型预测/缺陷与阻抗信号/对比选优/无语料降级）与 改迹调制（偏好对学十二维权重/个人回避库/可解释理由/上下文编辑对/在线重训/增量更新）、 神经风格编码（embedding 原型/语义混合检索，未配置自动降级）与 作者写作清单（L3 深层读取：五问自动归纳、红线强制保留、fineRead 入评分）与 姿态层细读前置（posture 健康度入评分，软性加权不拒绝生成）与 盲评统计（精确二项/95%CI/效应量）。
• 确定性兜底：任何 LLM 或网络不可用时，流程降级但不崩溃；真实模型不守规则时（大纲截断、 澄清不收尾）有确定性护栏兜底。
• 密钥安全：自动发现宿主配置的 API，绝不打印；提交前自动扫描密钥（CI 内置）。
• 不覆盖你的稿子：任何文件被外部改过，它都会停下让路，绝不悄悄覆盖。

路线图

已走到 v0.68：作者建模（四层风格体系：表层词汇句法 / 话语修辞 / 深层立场 / 元层选择偏好）、 改迹调制 V1.5 落地（个人 n-gram 模型 + 外层调制器：偏好对学习十二维权重，含个人回避库 与可解释层；增量在线更新，可选 embedding 神经编码 + 知识库语义混合检索 + L3 作者写作清单 + 姿态层细读 posture 前置，推理时调制；学习曲线显示几十次修改即可学到稳定方向）、 导演状态机与多 Agent 协作、 Web 伴随式工作台（选区 AI/候选卡/版本回滚/并排/图谱）、真实 LLM 可靠性修复、翻译方法论、 数学可视化。 接下来：意图分流训练、状态向量化、姿态层 LLM 细读精读特征（可选）、 V2 logprobs / V3 本地 DExperts 与激活转向、第三方盲评样本收集、跨语言语料验证。

---

由一群相信"AI 应该更懂人"的人做的开源项目。如果你也觉得 AI 写作差了一口气，欢迎来一起把它补上。