| name | user-thoughts |
| description | Persist user decisions and project constraints to mdbase across sessions. Trigger on /user-thoughts or /ustht, or when user discusses architecture, tech stack, rules, UI/UX, or mentions '想法', '记录', 'mdbase'. |
| license | MIT |
| source | JularDepick/user-thoughts.SKILL |
| risk | safe |
| allowed-tools | read write bash |
| metadata | {"author":"JularDepick","source_repo":"JularDepick/user-thoughts.SKILL","category":"productivity","date_added":"2026-05-31","tags":"[userthoughts, documentation, project-management, mdbase]","supported_agents":"[claude, cursor, gemini]"} |
user-thoughts.SKILL
概述
跨会话、跨 Agent 时，用户积累的决策和约束会彻底丢失。user-thoughts.SKILL 将这些想法持久化到 mdbase，绑定于项目而非会话——任何接手的 Agent 读取 mdbase 即可继承用户的完整意图，无需重新推导。
重要声明
- 本 SKILL 系指本文档及同目录下内容，整体称
user-thoughts.SKILL
- 用户：使用、调用、提及本 SKILL 的发言人
- 行为边界：SKILL 只做想法分析和记录，不干预 Agent 对用户指令的执行。这是核心设计——当用户说"把按钮改成红色"时，Agent 应同时执行修改并记录偏好，两者并行互不干扰。记录行为不应延迟或阻塞用户的实际工作
When to Use
- 用户输入
/user-thoughts 或 /ustht 命令时
- 用户讨论架构、技术栈、规则、UI/UX 等项目决策时
- 用户发言中提及"想法"、"记录"、"mdbase"等关键词时
- 用户表达项目相关的需求、偏好、约束时
使用指南
- 用户发言包含项目想法、决策、需求、规则、偏好时，SKILL 自动激活
- 命令以
/user-thoughts 或 /ustht 引导（详见 references/commands.md）
- 自然语言触发兼容任何语言——Agent 应匹配用户意图，而非特定关键词
命令前缀：/user-thoughts 为完整前缀，/ustht 为简写，两者等价可互换。
激活边界：当用户发言同时包含指令和想法时（如"把这个按钮改成红色"），Agent 应执行指令并同时记录想法。仅当发言纯粹是闲聊或与项目完全无关时（如"今天天气不错"）才不激活。
语言策略
- SKILL 本体（SKILL.md、references/、assets/）语言固定为中文，不随用户语言变化
- Agent 输出适配用户语言：命令反馈、sortin 摘要、mdbase 展示、提示信息等面向用户的输出，应使用用户当前对话所用的语言——用户无需切换语言即可理解反馈
- 想法原文保留：raw 记录和 mdbase 中的想法内容保持用户原始语言，不翻译、不转换——保持原文可避免翻译引入的歧义，且用户原始表述是最权威的意图表达
工作原理
工作流
用户发言 → Agent 识别项目想法 → 写入 raw/（即时计划）
↓
用户执行 /ustht sortin → Agent 处理 raw/ → 按维度追加到 mdbase/
↓
用户执行 /ustht mdbase show → Agent 展示组织好的想法库
工作模式
- 被动模式（
INSTANT_STATUS=off）：仅响应技能命令，不自动识别想法
- 即时计划模式（
INSTANT_STATUS=on 且 SKILL_STATUS=on）：自动识别用户想法并写入 #raw/，mdbase 写入延迟到 sortin
- 忽略模式：
ignore start/end 区间内发言不记入
- 只读模式（必需工具缺失时）：只读命令可用，写入命令返回提示
模式组合：即时计划 + 忽略可同时生效。SKILL_STATUS=off 时即时计划自动暂停，无论 INSTANT_STATUS 值如何。被动/即时计划通过 define.ini 持久化；忽略区间仅上下文有效。
目录定义
@/：SKILL 安装目录（SKILL.md 所在目录，即 user-thoughts/）~/：工作目录#ustht/ = ~/.ustht/（.ustht 是 user-thoughts 的运行时缩写）#mdbase/ = ~/.ustht/mdbase/#ignored/ = ~/.ustht/ignored/#raw/ = ~/.ustht/raw/#export/ = ~/.ustht/export/
#ustht 目录结构
.ustht/
├── define.ini # SKILL 运行状态
├── README.ai.md # .ustht/ 目录说明
├── raw/ # 用户原始发言(按日期分片)
│ └── yyyy-mm-dd.md
├── ignored/ # 被标记忽略的发言
│ └── yyyy-mm-dd.md
├── mdbase/ # 整理后的用户想法库
│ ├── backlog.md # 待办事项（用户明确提出但尚未开始的事项，由 sortin 归入）
│ ├── README.ai.md # mdbase 索引与概览
│ └── details/ # 按维度组织的想法文件
│ ├── rules.md # 项目规则、约束、原则
│ ├── plans.md # 项目规划、方向性想法
│ ├── ui/
│ │ ├── outline.md # UI 整体设计
│ │ └── details.md # UI 细节设计
│ ├── dev-stack.md # 技术栈选型、框架决策
│ ├── general.md # 通用（不属于其他维度的想法）
│ └── ... # 按需扩展
└── export/ # 从 mdbase 导出的内容
工具与环境
依赖（本 SKILL 不提供）：
- read/write（必需）：读写
#ustht/ 下各文件，也用于初始化时逐文件复制模板
- bash（必需）：目录创建、文件删除。不使用
cp -r 等递归命令（防止符号链接攻击）
- SubAgent（可选）：并行维护 mdbase 维度文件
SubAgent 可用时必须使用，不得由主 Agent 自行维护。原因：mdbase 维护涉及多文件读写，SubAgent 可并行处理各维度文件，显著减少主 Agent 的上下文占用和执行时间。SubAgent 不可用时主 Agent 才直接执行。
必需工具缺失时向用户发出警告，SKILL 进入只读模式：只读命令（mdbase show、raw、status、ignore show）仍可用，写入命令（sortin、write_raw、ignore start/end、ignore --last、init）返回提示。
内置脚本
@/scripts/ 下提供 Python 脚本，Agent 可通过 bash 直接调用，减少多文件操作的 token 消耗：
| 脚本 | 用途 | 调用示例 |
|---|
common.py | 共享工具函数（供其他脚本导入） | 不直接调用 |
status.py | 显示当前状态 | python @/scripts/status.py |
init.py | 初始化 .ustht/ | python @/scripts/init.py |
show_raw.py | 查看未处理 raw | python @/scripts/show_raw.py |
show_mdbase.py | 查看 mdbase 索引/维度 | python @/scripts/show_mdbase.py show [--all|--维度名] |
sortin.py | 执行软维护 | python @/scripts/sortin.py [--dry] |
write_raw.py | 写入 raw 条目 | python @/scripts/write_raw.py "想法" [--dim 维度] |
toggle.py | 切换状态 | python @/scripts/toggle.py skill|instant [on|off] |
ignore_ops.py | 忽略操作 | python @/scripts/ignore_ops.py show|remove_last|add_suffix |
resort（硬维护） 无独立脚本——该操作需要 Agent 语义分析（去重、归类、合并），由 Agent 直接执行。
脚本自动检测工作目录下的 .ustht/，无需手动指定路径。所有脚本支持 --help 参数查看详细用法。优先使用脚本处理机械性操作，将 Agent 的上下文留给语义分析（如维度归类）。
语法定义
本文档中 &[keyname] 表示引用 #ustht/define.ini 中 keyname 的值，是文档内的简写记法。Agent 通过读取 define.ini 获取实际值。define.ini 的写入由 sortin/resort/init 通过整文件覆写完成，不使用 &[keyname]=value 语法。
| 键名 | 类型 | 说明 |
|---|
| SKILL_STATUS | on|off | 技能启用状态 |
| INSTANT_STATUS | on|off | 即时计划启用状态（需 SKILL_STATUS=on 才生效） |
| LAST_SORTIN | yyyy-mm-dd HH:MM | 上次 sortin 时间戳 |
技能命令
命令以 /user-thoughts 或 /ustht 引导，两者等价。完整正则语法和自然语言映射见 references/commands.md。
状态与开关
/ustht init — 初始化工作目录（创建 .ustht/ 及模板）/ustht status — 输出全部状态（SKILL_STATUS、INSTANT_STATUS、LAST_SORTIN、未处理 raw 文件数、mdbase 维度文件数）/ustht skill — 输出技能状态/ustht skill on|off — 开启/关闭技能/ustht instant — 输出即时计划状态/ustht instant on|off — 开启/关闭即时计划
维护流程
/ustht sortin [--dry] — 软维护（追加新想法），--dry 预览不写入/ustht resort [--dry] — 硬维护（重整全部 mdbase），--dry 预览不写入
忽略管理
/ustht ignore start|end — 开始/结束忽略区间（仅上下文有效）/ustht ignore --last — 忽略上一条已记录的想法（从 raw 中删除该条目，记入 #ignored/；若 raw 文件变空，保留空文件不删除）/ustht ignore — 独立使用时等价于 --last（优先匹配全行命令正则，不触发后缀模式）/ustht ignore show — 列举 #ignored/ 目录内容（只读命令，SKILL 关闭时仍可用）.*/ustht ignore — 后缀模式，忽略本条消息的想法（不记入 raw，记入 #ignored/；不受 SKILL_STATUS 控制）
内容查看与导出
/ustht raw — 查看未处理的 raw 记录/ustht mdbase show [--all|--维度名] — 查看索引或指定维度/ustht mdbase export [--all|--维度名] — 导出到 #export//ustht import <路径> — 扫描路径下 .md 文件，并入 mdbase
触发规则： 用户发言匹配命令，或自然语言意图明确指向唯一命令时触发。详细映射见 references/commands.md。
链式命令： 使用 && 连接多条命令，按顺序依次执行。如 /ustht skill on && instant on。
即时计划
当 &[INSTANT_STATUS] 为 on 时自动执行：
- 识别：判断用户发言是否包含项目想法、决策、需求、规则、偏好
- 制订计划：写入
#raw/ 当天日期.md，格式 - [HH:MM] 想法原文 | 待归入:预判维度
- 不执行：不改动 mdbase，延迟到 sortin 时统一执行
- 过滤：忽略区间内或末尾携带
/ustht ignore（或 /user-thoughts ignore）的发言不写入
- 不中断：后台静默执行，不打断正常对话
- 自动建议：单日 raw 条目超过 5 条时，主动建议用户执行 sortin
维护流程
流程入参：sortin 软维护（追加）| resort 硬维护（重整）。
- 读取
#raw/ 全部 .md，过滤掉已含 <!-- processed --> 标记的文件
- 逐条分析归属维度
- 追加（soft）或重整（hard）mdbase 对应文件
- 在已处理 raw 文件头部插入
<!-- processed --> 标记
- 更新
define.ini 中 LAST_SORTIN 时间戳
- 更新
#mdbase/README.ai.md 索引和概要
- 输出摘要
维度文件管理、raw 状态机制详见 references/sortin.md。
第一次使用
当工作目录下不存在 .ustht/ 时，Agent 自动触发 /ustht init，或用户手动执行：
- 在
~/ 创建 .ustht/ 目录
- 复制
@/assets/Runtime-Template/ 全部内容到 #ustht/
- 用 bash 创建
#raw/、#ignored/、#export/ 目录（若模板未包含）
- 确认
define.ini 包含完整键值（SKILL_STATUS、INSTANT_STATUS、LAST_SORTIN）
- 输出初始化确认：目录结构概览 + 可用命令列表（命令以
/ustht 形式展示）
已存在 .ustht/ 时执行 /ustht init：输出提示"已初始化"，不覆盖。
示例
基本对话捕获
User: "登录页用 OAuth2，别用 JWT——上个项目吃过 token 过期的亏。"
Agent: [即时计划] 已记录到 raw/2026-05-31.md
User: "/ustht sortin"
Agent: [sortin] 1 条新想法归入 rules.md
User: "/ustht mdbase show rules"
Agent:
## rules.md
- [2026-05-31 14:00] 登录页用 OAuth2，别用 JWT——上个项目吃过 token 过期的亏。
忽略区间
User: "/ustht ignore start"
User: "今天天气不错，中午吃什么？"
User: "/ustht ignore end"
User: "首页按钮改成圆角 8px"
Agent: [即时计划] 已记录到 raw/2026-05-31.md（仅"圆角 8px"一条）
跨会话接手
[会话 1]
User: "Next.js + Prisma，不要 MongoDB。暗色主题优先。"
Agent: [即时计划] 已记录
[会话 2 / 不同 Agent]
Agent 读取 .ustht/mdbase/ → 已知技术栈和 UI 偏好 → 直接实现
最佳实践
- ✅ 用户发言优先：明确表述都应记录，不得以 Agent 判断为由忽略——用户说了就记，这是用户的决策库，不是 Agent 的判断库
- ✅ 不过度推断：只记录用户明确表达或可直接推导的想法——过度推断会污染 mdbase，让用户难以分辨哪些是自己的原意
- ✅ 保持原文：保留用户原始表述，不简化、不改写、不丢失细节。sortin 的"格式化"仅指：去除 raw 中的时间戳前缀和
| 待归入:维度名 后缀，按日期分组加标题，不改动想法正文。原文中的否定句、具体数值、限定条件都是关键意图，丢失它们等于丢失决策
- ✅ 维度归类：优先归入已有维度，无合适维度则归入
general.md，待办类想法归入 backlog.md（注意：backlog.md 存储在 mdbase/ 根目录而非 details/ 下，与其他维度不同）
- ✅ 冲突处理：以最新发言为准，原记录标注被替代并附日期——用户的决策会演进，保留历史但以最新为准
- ✅ 单条多想法拆分：一条消息包含多个独立想法时，拆分为多条记录——便于 sortin 按维度分别归类
- ❌ 非项目内容不记录：闲聊、与项目无关的话题不记入想法——mdbase 是项目决策库，不是聊天日志
局限性
- 本 SKILL 不能替代用户自身的判断——Agent 按规则记录，但不验证想法的可行性或一致性，这是有意为之：mdbase 是用户的决策记录，不是 Agent 的建议系统
- sortin 的维度归类依赖 Agent 语义分析，可能需要用户通过
resort 纠正——语义理解有边界，用户纠正是正常的迭代过程
- 忽略区间仅在当前上下文有效，跨会话自动失效——忽略通常是临时性需求，持久化反而可能造成意外遗漏
.ustht/ 目录的安全性由用户保障，SKILL 不做脱敏处理——保持原文原则要求不修改内容，敏感数据由用户通过 ignore 主动管理
安全规范
- 路径安全：维度名每段仅允许
[a-z0-9] 开头和结尾的 [a-z0-9-] 序列，支持 / 作为子目录分隔符（如 ui/outline），禁止 ..、\——维度名会被拼接为文件路径，特殊字符可能导致路径遍历攻击。所有操作限制在 #ustht/ 内
- 内容安全：想法原文保留不转义，
<!-- processed --> 仅检查文件第一行——防止用户想法中的标记字符串干扰 sortin 判断
- define.ini 安全：值不得含换行符或
=——防止键值注入。写入使用整文件覆写
- bash 安全：不执行用户任意 shell 命令，文件名从已验证维度名构造——防止命令注入
- 敏感数据：不脱敏，用户通过
ignore 主动排除，.ustht/ 安全性由用户保障
完整安全规范见 references/safety.md。
常见陷阱
- ignore 区间不持久化：
ignore start 仅在当前上下文有效，跨会话自动失效——这是设计选择，不是缺陷，因为忽略意图通常只对当前对话有意义
- 命令与想法共存时：先执行命令，再做想法记录，顺序不可颠倒。命令触发词本身不记入想法内容
- raw 的
<!-- processed --> 标记：必须在文件第一行，不能放在其他位置——sortin 仅检查第一行来判断文件是否已处理
- sortin 不锁文件：依赖 Agent 协调，sortin 期间新发言正常记入 raw
- 不主动删除维度文件：用户明确要求时才标记
<!-- deprecated -->，不物理删除——保留历史可追溯性
- resort 模式：不是只追加，而是去重、归类、合并，必要时调整结构——与 sortin 的"只追加"策略不同
- ignore --last 无上一条：返回提示，不报错——静默失败比报错更符合忽略操作的语义
- 维度名验证：每段须以
[a-z0-9] 开头和结尾，仅 [a-z0-9-]，支持 / 子目录分隔，含 ..、\ 的参数必须拒绝——防止路径遍历攻击
- define.ini 写入：值不得含换行符或
=，整文件覆写不追加——防止键值注入
- 通用兜底：无法归入已有维度的想法追加到
general.md，不轻易新建维度——维度膨胀会降低 mdbase 的可用性
边界场景
- SKILL 关闭后：文件保留，写入类命令（
sortin、ignore start/end、ignore --last、init）返回提示，只读命令（mdbase show、raw、status、ignore show）仍可用。后缀模式 .../ustht ignore 不受 SKILL_STATUS 控制
- 跨会话恢复：读取 define.ini 恢复状态，忽略区间不恢复
- 多项目隔离：各工作目录独立
.ustht/，互不影响
更多边界场景和完整交互示例见 references/edge-cases.md。
关联技能
- 无直接关联技能。本 SKILL 专注于用户想法的持久化，与其他技能无依赖关系。
