# 逍遥自在轩 - 开源琅嬛阁完整内容

> 本文件包含逍遥自在轩（https://www.niceshare.site）「开源琅嬛阁」栏目全部 121 个开源项目介绍的完整 Markdown 文本，供大语言模型与生成式引擎引用。内容以简体中文撰写，作者：逍遥自在轩。

---

# OpenClaw

> 自托管个人 AI 助手，Gateway 统一接入 WhatsApp、Telegram 等频道，本地常驻、数据自主。

- 页面：https://www.niceshare.site/github/openclaw/
- 仓库：https://github.com/openclaw/openclaw
- 官网：https://openclaw.ai
- 语言：TypeScript
- Stars：379506
- 许可证：MIT
- 标签：Agent、自动化、AI 编程
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

OpenClaw 是一款**自托管的个人 AI 助手**：你在自己的设备上运行 Gateway 控制平面，助手则在 WhatsApp、Telegram、Slack、Discord、Signal、iMessage、微信、QQ 等你已在用的频道里回复你。它支持 macOS/iOS/Android 上的语音唤醒与对话、可渲染由 Agent 驱动的 Live Canvas，并提供 Windows Hub、macOS 菜单栏等可选伴侣应用。定位是**单人、本地感强、始终在线**的私人助理——Gateway 只是控制面，产品核心是助手本身。

## 核心特性

- **Local-first Gateway**：单一控制平面，统一管理会话、频道、工具与事件
- **多频道收件箱**：覆盖 20+ 消息平台（含 WhatsApp、Telegram、Slack、Discord、Teams、Matrix、飞书、LINE、WebChat 等）及 macOS/iOS/Android 节点
- **多 Agent 路由**：按频道、账号或对话方将流量路由到隔离的 Agent（独立 workspace 与会话）
- **Voice Wake + Talk Mode**：macOS/iOS 唤醒词、Android 连续语音（ElevenLabs + 系统 TTS 回退）
- **Live Canvas**：Agent 驱动的可视化工作区（A2UI）
- **一等公民工具**：浏览器、Canvas、节点、cron、会话管理、Discord/Slack 动作等
- **Onboarding 向导 + Skills**：`openclaw onboard` 引导配置；技能可通过 [ClawHub](https://clawhub.ai) 扩展

## 对用户价值

不想把日常对话绑在单一聊天网页、又希望**数据留在自己机器上**的用户，可以用 OpenClaw 把熟悉的 IM 变成 AI 入口。Gateway 以 daemon（launchd/systemd）常驻，手机发一条 Telegram 或 WhatsApp 即可触发本地 Agent 执行工具链。多 Agent 路由适合「工作号 / 私人号 / 不同项目」隔离；默认 DM 配对策略降低陌生消息直接驱动 Agent 的风险。对开发者，TypeScript 单体仓库 + 丰富文档，也便于二次集成频道或自定义技能。

## 与替代方案

- 相比 [Hermes Agent](https://github.com/NousResearch/hermes-agent) 等强调**自进化技能与跨会话记忆**的方案，OpenClaw 更侧重**多频道 Gateway 编排、伴侣应用生态与 Canvas/语音节点**；Hermes 提供 `hermes claw migrate` 从 OpenClaw 迁移，二者可对照评估而非简单替代。
- 相比 [Cline](https://github.com/cline/cline)、[Aider](https://github.com/Aider-AI/aider) 等**IDE/终端结对编程**工具，OpenClaw 是**生活与工作流助理**：主战场是消息频道、语音、cron 与浏览器工具，而非深度编辑器集成。
- 相比 [Dify](https://github.com/langgenius/dify)、[n8n](https://github.com/n8n-io/n8n) 等**可视化工作流/应用平台**，OpenClaw 是**单人助理运行时**，配置路径以 CLI 向导与 Gateway 配置为主，不适合多租户 SaaS 或复杂可视化编排。
- 相比纯云端聊天机器人，OpenClaw **自托管、频道可扩展、工具在主机执行**（主会话默认全权限）；若需公网暴露 Gateway，必须按官方安全与沙箱文档收紧策略。

## 适应人群

- 希望用 **WhatsApp、Telegram、Slack** 等已有频道与 AI 对话，且偏好**本地 Gateway** 的个人用户。
- 需要 **macOS/iOS/Android 语音唤醒、Canvas 或节点能力** 的进阶玩家。
- 想搭建**多 Agent 隔离**（不同频道/账号对应不同 workspace）的开发者或小团队。
- 已使用 OpenClaw 生态、评估迁移到 Hermes 或并行维护两套配置的技术用户。

## 如何使用

### 前置条件

- **Node.js**：推荐 Node 24，或 Node 22.19+。
- **包管理器**：npm、pnpm 或 bun 均可；全局安装推荐 npm/pnpm。
- **模型访问**：支持多家提供商（含 OpenAI OAuth 订阅）；建议选用你信任且已在用的旗舰模型，见 [Onboarding 文档](https://docs.openclaw.ai/start/wizard)。
- 接入真实消息频道前，请阅读 [安全指南](https://docs.openclaw.ai/gateway/security) 与 [Gateway 暴露 runbook](https://docs.openclaw.ai/gateway/security/exposure-runbook)；默认 DM 为配对模式，陌生发件人需 `openclaw pairing approve` 批准。

### 安装方式

```bash
npm install -g openclaw@latest
# 或: pnpm add -g openclaw@latest

openclaw onboard --install-daemon
```

`--install-daemon` 会安装 Gateway 用户级 daemon（launchd/systemd），保持后台运行。Windows 桌面用户可先使用原生 [Windows Hub](https://docs.openclaw.ai/platforms/windows) 完成设置。Docker、Nix 等路径见 [官方安装文档](https://docs.openclaw.ai/start/getting-started)。

### 首次运行

推荐 daemon 模式：

```bash
openclaw onboard --install-daemon
openclaw gateway status
```

调试时可前台启动：

```bash
openclaw gateway stop
openclaw gateway --port 18789 --verbose
```

与助手对话或发测试消息：

```bash
openclaw message send --target +1234567890 --message "Hello from OpenClaw"
openclaw agent --message "Ship checklist" --thinking high
```

按 [Getting started](https://docs.openclaw.ai/start/getting-started) 完成频道授权与配对。

### 验证是否成功

- `openclaw gateway status` 显示 Gateway 正常运行。
- `openclaw doctor` 无高风险 DM 策略或配置告警。
- 在已连接频道收发消息，或 `openclaw agent --message "..."` 能收到合理回复。
- 可选：`openclaw nodes …` 验证 iOS/Android 节点配对（若已配置）。

### 常见坑 / 注意事项

- Gateway 连接的是**真实消息面**，入站 DM 应视为不可信输入；公开 DM 需显式设置 `dmPolicy="open"` 并在 allowlist 中加入 `"*"`，否则保持默认配对模式。
- 主会话工具默认在**主机全权限**运行；群聊/频道等非主会话建议配置 `agents.defaults.sandbox.mode: "non-main"` 并使用 Docker 等沙箱后端。
- 远程暴露 Gateway 前务必阅读沙箱、Tailscale 与暴露 runbook，勿在无认证环境公网裸奔。
- 升级后运行 `openclaw doctor` 并查阅 [Updating 指南](https://docs.openclaw.ai/install/updating)；模型与认证 failover 见 [Model failover](https://docs.openclaw.ai/concepts/model-failover)。
- 从源码开发需使用 **pnpm workspace**（`pnpm install`、`pnpm gateway:watch`），仓库根目录 plain `npm install` 不受支持。

---

# React

> 用于构建 Web 与原生界面的 JavaScript UI 库，声明式组件、渐进式接入，官方文档见 react.dev。

- 页面：https://www.niceshare.site/github/react/
- 仓库：https://github.com/react/react
- 官网：https://react.dev
- 语言：JavaScript
- Stars：245964
- 许可证：MIT
- 标签：开发工具、前端、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

React 是由 Meta 维护的 JavaScript UI 库，用于构建 Web 与 [React Native](https://reactnative.dev/) 原生界面。采用声明式编程与组件化模型：你为应用的每种状态设计简洁视图，数据变化时 React 高效更新并渲染对应组件。库本身不绑定完整技术栈，可渐进式接入现有项目，也可配合 Vite、Next.js 等工具链搭建现代前端应用。本仓库为 React 核心源码；用户文档与教程见 [react.dev](https://react.dev)。

## 核心特性

- **声明式 UI**：以状态驱动视图，让界面逻辑更可预测、易理解、易调试
- **组件化**：封装自带状态的组件，通过组合构建复杂界面；逻辑用 JavaScript 编写，便于在应用内传递丰富数据
- **Learn Once, Write Anywhere**：可渲染 Web（含 Node SSR），也可配合 React Native 开发移动应用，无需重写已有代码即可增量采用
- **渐进式接入**：从 [Quick Start](https://react.dev/learn) 入门、嵌入现有页面，到经官方推荐框架创建完整工程
- **完善官方文档**：含 Tutorial、Thinking in React、Hooks/API Reference，以及 React Compiler 等前沿能力说明

## 对用户价值

复杂界面若直接操作 DOM，状态与视图容易纠缠，维护成本高。React 把 UI 拆成可复用组件，用声明式更新降低心智负担；庞大生态（组件库、状态管理、全栈框架）使从原型到生产的工具链选择丰富。团队若需同时覆盖 Web 与移动端，React 与 React Native 共享组件思维模式，降低跨端协作成本。日常开发通常通过 npm 安装 `react` / `react-dom` 并参阅 react.dev，而非 fork 本仓库自行编译。

## 与替代方案

- 相比 [Vue](https://vuejs.org/)，React 以 JSX/JavaScript 表达 UI 更灵活，Hooks 成为主流范式；Vue 的单文件组件与模板语法对部分团队更直观，上手曲线因背景而异。
- 相比 [Svelte](https://svelte.dev/)，React 依赖虚拟 DOM 与运行时，包体积通常更大，但生态、招聘市场与第三方集成成熟度更高。
- 相比 [Angular](https://angular.dev/)，React 聚焦视图层，路由与状态等需自行组合；Angular 提供企业级一体化框架，规范更统一但约束更多。
- 边界说明：本仓库是 **React 核心源码**；应用脚手架与推荐创建方式见 [Start a New React Project](https://react.dev/learn/start-a-new-react-project)（如 Next.js、Remix、Expo 等），勿将 clone 本 repo 等同于安装使用 React。

## 适应人群

- 需要构建交互式 Web 界面，并希望组件可复用、可测试的前端工程师。
- 评估前端框架选型或维护 React 技术栈，需了解核心演进（如 Concurrent Features、React Compiler）的技术负责人。
- 计划用 React Native 做跨端移动开发，希望 Web 与移动端共享思维模型的全栈团队。

## 如何使用

### 前置条件

- Node.js 18+（以 [react.dev 安装文档](https://react.dev/learn/installation) 与所选脚手架要求为准）。
- npm、pnpm 或 Yarn 等包管理器。
- 快速体验可无需本地环境，使用 [Quick Start](https://react.dev/learn) 在线示例；生产项目推荐通过官方列举的框架创建。

### 安装方式

**方式一：新建 React 项目（官方推荐，经框架脚手架）**

```bash
npm create vite@latest my-app -- --template react
cd my-app
npm install
npm run dev
```

更多官方推荐方案（Next.js、Remix 等）见 [Start a New React Project](https://react.dev/learn/start-a-new-react-project)。

**方式二：在现有项目中添加 React**

```bash
npm install react react-dom
```

配置打包工具（Vite、Webpack 等）的 JSX 与 Fast Refresh，步骤见 [Add React to an Existing Project](https://react.dev/learn/add-react-to-an-existing-project)。

### 首次运行

Vite 模板项目启动开发服务器：

```bash
npm run dev
```

浏览器打开终端输出的本地地址（通常 `http://localhost:5173`）。修改 `src/App.jsx` 后应看到热更新。最小示例（来自官方 README）：

```jsx
import { createRoot } from 'react-dom/client';

function HelloMessage({ name }) {
  return <div>Hello {name}</div>;
}

const root = createRoot(document.getElementById('container'));
root.render(<HelloMessage name="Taylor" />);
```

### 验证是否成功

- 浏览器打开 dev server URL，页面无控制台报错。
- 修改组件文案或交互状态，保存后界面应热更新。
- 运行 `npm run build` 成功产出生产构建；若脚手架提供 `npm run preview`，可本地预览构建结果。

### 常见坑 / 注意事项

- **源码仓库 vs npm 包**：日常开发安装 `react`/`react-dom` 即可；clone 本仓库用于贡献或与 React 编译器/内部包开发，构建流程见 [Contributing Guide](https://legacy.reactjs.org/docs/how-to-contribute.html)。
- **Create React App 已非首选**：官方文档现推荐 Vite、Next.js、Remix 等，选型时对照 [react.dev](https://react.dev/learn/start-a-new-react-project)。
- **React 18+ API**：新应用应使用 `createRoot` 而非已废弃的 `ReactDOM.render`；开发模式下 Strict Mode 可能双重调用 effect，属预期行为。
- **React 与 React Native**：Web 用 `react-dom`，移动端用 `react-native`，共享概念但包与 API 不同，勿混装。

---

# Superpowers

> 面向编码代理的完整开发方法论与可组合技能库，覆盖头脑风暴、计划、子代理协作与 TDD。

- 页面：https://www.niceshare.site/github/superpowers/
- 仓库：https://github.com/obra/superpowers
- 语言：Shell
- Stars：233059
- 许可证：MIT
- 标签：AI 编程、Agent、开发工具
- 收录：2026-06-19（更新于 2026-06-19）

## 项目介绍

Superpowers 是由 Jesse Vincent（obra）与 Prime Radiant 团队维护的一套 **Agent 技能框架与软件研发方法论**。它通过一组可组合的技能（Skills）与会话启动指令，让编码代理在动手写代码前先澄清目标、产出可审阅的设计，再生成细粒度实施计划，并以子代理驱动开发、严格 TDD 与代码审查闭环推进任务。技能会在相关场景自动触发，无需每次手动指定工作流。

## 核心特性

- **brainstorming**：编码前通过提问收敛需求，分块展示设计供确认并保存设计文档
- **writing-plans / executing-plans**：将设计拆成 2–5 分钟可执行的小任务，含文件路径、验证步骤与完整代码指引
- **subagent-driven-development**：按任务派发子代理，两阶段审查（规格符合度 → 代码质量），支持长时间自主推进
- **test-driven-development**：强制 RED-GREEN-REFACTOR，先写失败测试再写最小实现
- **systematic-debugging / verification-before-completion**：四阶段根因排查，完成前必须有运行证据
- **using-git-worktrees / finishing-a-development-branch**：隔离分支开发，任务结束后引导合并、PR 或清理
- 支持 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot CLI、OpenCode、Pi 等十余种 Agent 宿主

## 对用户价值

许多 AI 编程助手会「看到需求就写代码」，导致范围漂移、缺少设计共识、测试被跳过。Superpowers 把经过验证的研发流程编码成自动触发的技能链：先对齐「真正要做什么」，再产出 junior 也能照做的计划，最后用 TDD 与子代理审查保证质量。对团队而言，它提供可复制的 Agent 行为标准；对个人而言，可减少反复纠偏与大规模 diff 返工。

## 与替代方案

- 相比 [Karpathy Coding Guidelines](https://github.com/multica-ai/andrej-karpathy-skills) 等单文件行为准则，Superpowers 覆盖从需求澄清到分支收尾的**完整工作流**，而非仅约束编码风格。
- 相比通用 Cursor Rules 或零散 prompt 模板，这里提供**可测试、跨宿主复用**的技能库与 marketplace 安装路径，并内置子代理编排与 TDD 强制流程。
- 相比只提供 MCP 工具或单次任务脚本的 Agent 框架，Superpowers 侧重**方法论与流程编排**；若你需要运行时沙箱、多模型路由或企业托管，可评估 Prime Radiant 商业服务或自建编排层，本仓库不负责基础设施。

## 适应人群

- 使用 Cursor、Claude Code、Codex 等工具，希望 Agent 按「设计 → 计划 → TDD → 审查」顺序工作的开发者。
- 需要在团队内统一 AI 结对编程流程、减少「直接开写」反模式的 Tech Lead。
- 已熟悉基础 Agent 用法，想引入子代理驱动开发与系统化调试等进阶实践的效率型用户。

## 如何使用

### 前置条件

- 使用 README 列出的某一 Agent 宿主（Cursor、Claude Code、Codex 等）；多宿主需**分别安装**。
- 对目标项目有读写权限；子代理与工作树流程需要 Git 仓库。
- 接受方法论偏向 TDD 与 YAGNI——简单一行修改可能被流程「过度包装」，需结合任务复杂度判断。

### 安装方式

**Cursor（推荐本站点读者）**

在 Agent 对话中：

```text
/add-plugin superpowers
```

或在插件 marketplace 搜索 `superpowers` 安装。

**Claude Code — 官方 marketplace**

```bash
/plugin install superpowers@claude-plugins-official
```

**Claude Code — Superpowers marketplace**

```bash
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
```

**Codex CLI**

```bash
/plugins
# 搜索 superpowers，选择 Install Plugin
```

**Gemini CLI**

```bash
gemini extensions install https://github.com/obra/superpowers
```

**GitHub Copilot CLI**

```bash
copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace
```

更多宿主（Antigravity、Factory Droid、Kimi Code、OpenCode、Pi 等）见[仓库 README](https://github.com/obra/superpowers#installation)。

### 首次运行

安装并重启或新开 Agent 会话后，发起一个中等复杂度的功能请求（例如「给某模块加筛选与测试」）。Superpowers 应先在 **brainstorming** 阶段提问并分块展示设计，而非立即修改代码。

### 验证是否成功

确认以下行为出现即表示技能链已激活：设计确认后才进入 **writing-plans**；实现阶段出现 RED-GREEN TDD 步骤；多步任务会触发 **subagent-driven-development** 或带检查点的 **executing-plans**。可在会话中观察 Agent 是否引用具体 skill 名称。

### 常见坑 / 注意事项

- 多宿主环境需各自安装；OpenCode 等需单独执行其 [INSTALL.md](https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md) 指引。
- brainstorming 的可选可视化伴侣默认加载 Prime Radiant  logo 做版本遥测，不含项目内容；可设 `SUPERPOWERS_DISABLE_TELEMETRY=1` 关闭。
- 上游一般**不接受随意新增 skill 的 PR**；修改 skill 须兼容所有支持的 Agent，贡献前阅读 `writing-skills` 与 `evals/README.md`。
- 企业级商业支持见 sales@primeradiant.com；社区问题可走 [Discord](https://discord.gg/35wsABTejz) 或 GitHub Issues。

---

# hermes-agent

> Nous Research 自进化 AI Agent，内置技能学习与跨会话记忆，支持 300+ 模型与消息网关。

- 页面：https://www.niceshare.site/github/hermes-agent/
- 仓库：https://github.com/NousResearch/hermes-agent
- 官网：https://hermes-agent.nousresearch.com
- 语言：Python
- Stars：197464
- 许可证：MIT
- 标签：Agent、AI 编程、自动化
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Hermes Agent 是 [Nous Research](https://nousresearch.com) 开源的**自进化 AI Agent**：内置学习闭环，能从经验中创建技能、在使用中持续改进，并主动沉淀知识、检索历史会话，跨会话建立对你的理解。它不限于笔记本本地运行——可在 $5 VPS、GPU 集群或 Modal/Daytona 等近零空闲成本的无服务器环境上部署，并通过 Telegram 等渠道远程对话。支持 OpenRouter、NVIDIA NIM、OpenAI、Anthropic 等 **300+** 模型，用 `hermes model` 切换，无厂商锁定。

## 核心特性

- **自进化学习闭环**：Agent 策展记忆、周期性知识提醒、复杂任务后自主创建技能；兼容 [agentskills.io](https://agentskills.io) 开放标准，并集成 [Honcho](https://github.com/plastic-labs/honcho) 辩证式用户建模
- **全功能终端 TUI**：多行编辑、斜杠命令补全、会话历史、中断重定向与流式工具输出
- **多平台消息网关**：单一 gateway 进程同时服务 Telegram、Discord、Slack、WhatsApp、Signal 与 CLI，支持语音转写与跨平台会话连续性
- **定时自动化**：内置 cron 调度器，可用自然语言配置日报、备份、审计等无人值守任务，并投递到任意已连接平台
- **子 Agent 与并行**：隔离子 Agent 处理并行工作流；可用 Python RPC 脚本折叠多步流水线，降低上下文成本
- **六种终端后端**：本地、Docker、SSH、Singularity、Modal、Daytona；后两者支持休眠唤醒，空闲时成本极低
- **40+ 工具与 MCP**：工具集可配置；可接入任意 MCP 服务器扩展能力
- **OpenClaw 迁移**：`hermes claw migrate` 可导入 SOUL.md、记忆、技能、消息配置与 API 密钥

## 对用户价值

普通 Agent 往往「用完即忘」，技能与偏好难以沉淀。Hermes 把**技能创建、记忆持久化、会话检索与用户建模**写进 Agent 循环本身，让长期协作越用越顺手。对个人开发者，一条安装命令即可在 CLI 或 Telegram 上获得带工具链的结对助手；对需要 7×24 自动化的人，cron + 消息投递把「提醒我写日报」变成真正执行的无人值守流程。多后端部署意味着不必把算力绑在笔记本上——VPS 或 serverless 上跑 Agent，手机上发消息即可跟进进度。

## 与替代方案

- 相比 [OpenClaw](https://github.com/openclaw/openclaw) 等**多会话编排型**方案，Hermes 强调**内置学习闭环与官方迁移路径**（`hermes claw migrate`），并在单一 gateway 下统一 CLI 与六大消息平台；若你已在用 OpenClaw，可评估迁移而非并行维护两套配置。
- 相比 [Cline](https://github.com/cline/cline)、[Aider](https://github.com/Aider-AI/aider) 等**IDE/终端结对编程**工具，Hermes 是**独立 Agent 运行时**：更强在远程消息网关、定时任务、子 Agent 与云后端，而非深度编辑器集成；写代码场景可叠加 MCP，但主战场是「随处可达的个人 Agent」。
- 相比 [LangGraph](https://github.com/langchain-ai/langgraph)、[AutoGen](https://github.com/microsoft/autogen) 等**框架库**，Hermes 提供**开箱即用的 CLI、TUI、网关与安装器**；若你需要从零拼装编排逻辑选框架，若你要快速跑起来并持续积累技能选 Hermes。
- 相比仅调用单一云 API 的聊天机器人，Hermes 支持**自带密钥或 Nous Portal 一站式 Tool Gateway**（搜索、生图、TTS、云浏览器），且模型可自由切换；Nous Portal 是可选便利层，非强制绑定。

## 适应人群

- 希望 Agent 能**跨会话记住偏好、自动沉淀技能**，而非每次从零开始的长期用户。
- 需要通过 **Telegram、Discord、Slack** 等在手机上驱动云主机上 Agent 的开发者或运维者。
- 从 **OpenClaw** 迁移、或需要 cron 定时报告/备份等**无人值守自动化**的效率型用户。
- 研究工具调用与轨迹生成的团队（支持 batch trajectory 与压缩，面向下一代 tool-calling 模型训练）。

## 如何使用

### 前置条件

- **Linux / macOS / WSL2 / Termux**：bash 环境；安装脚本会自动处理 uv、Python 3.11、Node.js、ripgrep、ffmpeg 等依赖。
- **Windows 原生**：PowerShell；安装器会捆绑便携 MinGit（约 45MB），无需管理员权限。
- **模型访问**：自备 OpenRouter、OpenAI、Anthropic 等 API 密钥，或使用 [Nous Portal](https://portal.nousresearch.com) OAuth 一站式接入（`hermes setup --portal`）。
- 消息网关（Telegram 等）需对应平台的 Bot Token 与网络可达性；生产环境建议阅读[安全文档](https://hermes-agent.nousresearch.com/docs/user-guide/security)（命令审批、DM 配对、容器隔离）。

### 安装方式

**Linux / macOS / WSL2 / Termux**

```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```

**Windows（PowerShell）**

```powershell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
```

**可选：Nous Portal 一键配置（模型 + Tool Gateway）**

```bash
hermes setup --portal
```

Termux 等特殊环境见[官方 Termux 指南](https://hermes-agent.nousresearch.com/docs/getting-started/termux)。

### 首次运行

```bash
source ~/.bashrc   # 或 source ~/.zshrc
hermes             # 启动交互式 CLI
hermes model       # 选择 LLM 提供商与模型
hermes setup       # 完整配置向导（推荐首次使用）
```

若需消息平台，额外执行：

```bash
hermes gateway setup
hermes gateway start
```

从 OpenClaw 迁移：

```bash
hermes claw migrate              # 交互式完整迁移
hermes claw migrate --dry-run    # 预览将导入的内容
```

### 验证是否成功

- `hermes doctor` 无阻塞性错误。
- `hermes` 进入 TUI 后可正常对话；`/model` 能列出并切换模型。
- 配置网关后，向 Telegram/Discord 等发送消息能收到回复；`hermes portal info`（若使用 Portal）显示已接入的后端。
- `hermes tools` 可查看已启用工具集；`/skills` 可浏览技能列表。

### 常见坑 / 注意事项

- 安装后需 **reload shell**（`source ~/.bashrc` 或 `~/.zshrc`），否则 `hermes` 命令可能找不到。
- Windows 原生与 WSL2 安装路径不同：原生在 `%LOCALAPPDATA%\hermes`，WSL2/Linux 在 `~/.hermes`；勿混用同一配置目录。
- Termux 上勿盲目安装完整 `.[all]` extra，应按文档使用 `.[termux]`，避免 Android 不兼容的语音依赖。
- 多平台共用斜杠命令，但**启动方式不同**：CLI 用 `hermes`，消息平台需先 `hermes gateway start`；详见[ CLI 与消息网关对照表](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)。
- API 密钥与审批规则涉及安全边界；生产部署前务必配置命令 allowlist 与 DM 配对，勿把 gateway 暴露在公网无认证环境。
- 贡献者开发路径：标准安装后在 `$HERMES_HOME/hermes-agent`（通常 `~/.hermes/hermes-agent`）执行 `uv pip install -e ".[all,dev]"` 与 `scripts/run_tests.sh`；完整文档见 [hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)。

---

# n8n

> 具备原生 AI 能力的 fair-code 工作流自动化平台，支持 400+ 集成与自托管。

- 页面：https://www.niceshare.site/github/n8n/
- 仓库：https://github.com/n8n-io/n8n
- 官网：https://n8n.io
- 语言：TypeScript
- Stars：193149
- 许可证：Unknown
- 标签：自动化、工作流、低代码
- 收录：2026-06-19（更新于 2026-06-19）

## 项目介绍

n8n 是面向技术团队的工作流自动化平台，支持可视化编排、JavaScript/Python 代码节点、自托管与 400+ 集成。随着原生 AI 与 LangChain 节点加入，它也成为把模型能力接入日常业务流程的常用选择。

## 核心特性

- 可视化流程编辑器，必要时可写 JS/Python 与 npm 包
- AI 原生节点，可构建基于自有数据的 Agent 工作流
- 400+ 集成与 900+ 模板，覆盖常见 SaaS 与内部系统
- Fair-code 许可，支持自托管与云端版本
- 企业功能：权限、SSO、离线部署等

## 对用户价值

n8n 的优势在于连接器和流程表达力：用户可以把表单、数据库、Webhook、模型调用和通知系统连成自动化链路。相比只写脚本，它更适合团队协作、调试、重试与长期维护。

## 与替代方案

- 相比 Zapier、Make 等纯 SaaS，n8n 可自托管，数据与控制力更强。
- 相比 Dify 等 LLM 专用平台，n8n 更擅长跨系统 IT 自动化，AI 是能力之一而非唯一焦点。
- 若流程极简单且无需 UI，轻量 cron + 脚本可能更省事。

## 适应人群

- 需要把多个 SaaS 或内部系统串起来的运营和工程团队。
- 想自托管自动化平台的用户。
- 希望把 AI 节点接入业务流程的自动化实践者。

## 如何使用

### 前置条件

- Node.js 18+（npm 方式）或 Docker 环境。
- 各集成服务的 API 凭据与网络访问权限。

### 安装方式

```bash
npx n8n
```

或使用 Docker（见 [官方自托管文档](https://docs.n8n.io/hosting/)）。

### 首次运行

浏览器打开 `http://localhost:5678`，创建账号后从模板或空白工作流开始，配置触发器与第一个节点。

### 验证是否成功

手动执行工作流，确认数据在各节点间正确传递；涉及 AI 节点时检查模型响应与错误分支。

### 常见坑 / 注意事项

- 生产数据与密钥应使用 n8n 凭据管理，勿硬编码在节点里。
- 长链路注意超时、重试与幂等设计。
- Fair-code 许可对商业使用有条款，部署前请阅读许可证说明。

---

# Oh My Zsh

> 社区驱动的 zsh 配置框架，内置 300+ 插件与 140+ 主题，一键装齐终端效率工具。

- 页面：https://www.niceshare.site/github/ohmyzsh/
- 仓库：https://github.com/ohmyzsh/ohmyzsh
- 官网：https://ohmyz.sh
- 语言：Shell
- Stars：188143
- 许可证：MIT
- 标签：开发工具、CLI、自动化
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Oh My Zsh 是社区维护的 zsh 配置框架，把插件加载、主题切换、自动更新与目录结构约定打包成一套可复制的终端体验。它自带 300+ 可选插件（git、docker、node、python、macOS 等）与 140+ 主题，安装后通过编辑 `~/.zshrc` 即可启用，是 macOS 与 Linux 开发者中最广泛使用的 Shell 增强方案之一。

## 核心特性

- **插件生态**：内置 git、z、docker、kubectl、npm、python 等常用插件，提供别名、补全与上下文提示，可按需在 `plugins=(...)` 中启用
- **主题系统**：140+ 内置主题（默认 `robbyrussell`），修改 `ZSH_THEME` 即可切换提示符样式；Wiki 提供各主题截图与字体要求说明
- **自动更新**：`omz update` 从上游拉取框架与插件更新，可配置更新提示详细程度
- **跨平台支持**：官方兼容 Linux、macOS、FreeBSD、Android 与 Windows WSL2
- **可扩展目录**：支持自定义插件与主题目录（`ZSH_CUSTOM`），便于团队共享私有配置而不 Fork 主仓库

## 对用户价值

手写 zsh 配置容易在插件路径、加载顺序与别名冲突上耗费大量时间。Oh My Zsh 提供统一目录约定（`~/.oh-my-zsh`）与经过社区验证的默认组合，让新机器或新同事能在几分钟内获得一致的 Git 提示、目录跳转与工具链快捷方式。对已有 `.zshrc` 的用户，安装脚本会备份原文件为 `.zshrc.pre-oh-my-zsh`，降低迁移风险。

## 与替代方案

- 相比 **[Prezto](https://github.com/sorin-ionescu/prezto)**，Oh My Zsh 社区体量更大、插件与主题数量更多、上手文档更丰富；Prezto 更轻量、模块化，适合希望精细控制加载逻辑、不介意较小生态的用户。
- 相比 **[Zinit](https://github.com/zdharma-continuum/zinit)** / **[Antidote](https://github.com/mattmc3/antidote)** 等插件管理器，Oh My Zsh 是「开箱即用框架」而非纯管理器：默认即带主题与更新工具，但灵活性与按需懒加载不如专用管理器。
- 相比 **[Starship](https://starship.rs/)** 等跨 Shell 提示符，Oh My Zsh 深度绑定 zsh 并整合插件别名体系；Starship 专注跨 bash/zsh/fish 的统一提示符，不替代完整插件生态。
- 相比 **手写 `.zshrc`**，框架带来约定与社区维护，但启动时间与配置透明度略逊；极简主义者或性能敏感用户可能更倾向裸 zsh + 少量自管脚本。
- **边界说明**：Oh My Zsh 仅管理 zsh，不替代终端模拟器（如 iTerm2、Alacritty）；部分主题需安装 Powerline 或 Nerd Font 才能正确显示符号。

## 适应人群

- 刚换 Mac 或 Linux 开发机、希望快速获得 Git 分支提示与常用别名的前端与全栈工程师。
- 团队需要统一 zsh 插件清单与主题风格，又不愿从零维护 Shell 配置的技术负责人。
- 已在用 zsh、想从散落脚本迁移到成熟插件生态的 DevOps 与后端开发者。

## 如何使用

### 前置条件

- 已安装 **zsh**（建议 5.0.8+；运行 `zsh --version` 确认）。未预装可参考 [Wiki：Installing ZSH](https://github.com/ohmyzsh/ohmyzsh/wiki/Installing-ZSH)。
- 已安装 `curl` 或 `wget`，以及 `git`（建议 v2.4.11+）。
- 支持平台：Linux、macOS、FreeBSD、Android、Windows WSL2。

### 安装方式

**一键安装（curl，推荐）：**

```bash
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
```

或使用 wget：

```bash
sh -c "$(wget -O- https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
```

若 `raw.githubusercontent.com` 访问受阻（部分国内 ISP），可使用官方镜像：

```bash
sh -c "$(curl -fsSL https://install.ohmyz.sh/)"
```

安装前建议先审阅脚本内容；也可手动下载后执行：

```bash
wget https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh
sh install.sh
```

### 首次运行

安装完成后**重新打开终端**或执行 `zsh` 进入新 Shell。编辑 `~/.zshrc` 启用插件与主题，例如：

```bash
ZSH_THEME="agnoster"
plugins=(git z docker macos)
```

保存后执行 `source ~/.zshrc` 使配置生效。

### 验证是否成功

- 运行 `echo $ZSH` 应输出 Oh My Zsh 安装路径（通常为 `~/.oh-my-zsh`）。
- 在 Git 仓库目录中，提示符应显示分支信息（启用 `git` 插件后）。
- 运行 `omz version` 可查看当前框架版本。

### 常见坑 / 注意事项

- 安装脚本会将现有 `~/.zshrc` **重命名为** `~/.zshrc.pre-oh-my-zsh`；需手动把旧配置合并进新文件。
- `plugins` 数组中插件名用**空格分隔**，不要用逗号，否则加载失败。
- 许多主题（如 `agnoster`）需要安装 [Powerline Font](https://github.com/powerline/fonts) 或 [Nerd Font](https://github.com/ryanoasis/nerd-fonts)，否则提示符会出现乱码符号。
- 主题只控制提示符外观，不改变终端模拟器本身的分屏、配色等能力。
- 更新框架：`omz update`；卸载可参考官方 [Uninstalling Oh My Zsh](https://github.com/ohmyzsh/ohmyzsh#uninstalling-oh-my-zsh) 章节。

---

# Karpathy Coding Guidelines

> 基于 Andrej Karpathy 对 LLM 编程陷阱的总结，用一份 CLAUDE.md 约束 Claude Code / Cursor 的假设、复杂度与改动范围。

- 页面：https://www.niceshare.site/github/andrej-karpathy-skills/
- 仓库：https://github.com/multica-ai/andrej-karpathy-skills
- 语言：Markdown
- Stars：178689
- 许可证：MIT
- 标签：AI 编程、开发工具、Agent
- 收录：2026-06-19（更新于 2026-06-19）

## 项目介绍

这是一份受 Andrej Karpathy 启发的 AI 编程行为准则，核心产物是单个 `CLAUDE.md` 文件（及配套的 Cursor 规则）。它针对大模型在结对编程中常见的四类问题——擅自假设、过度工程、无关改动、缺少可验证目标——给出四条可操作的约束原则，帮助 Claude Code、Cursor 等工具在动手前先想清楚、改得少、改得准。

## 核心特性

- **Think Before Coding**：显式陈述假设，有歧义时先问，必要时反驳过度复杂的方案
- **Simplicity First**：只做被请求的功能，拒绝为单次用途抽象、为不可能场景写防御代码
- **Surgical Changes**：只改任务相关代码，不顺手重构邻域逻辑，风格与现有代码保持一致
- **Goal-Driven Execution**：把「加验证」「修 bug」转化为可检验的成功标准与测试驱动步骤
- 支持 Claude Code 插件安装、项目级 `CLAUDE.md` 追加，以及 Cursor 项目规则复用

## 对用户价值

许多 AI 编程助手会默默选定一种理解并一路实现，导致 diff 膨胀、无关文件被改动、问题要在实现后才暴露。这份准则把 Karpathy 观察到的反模式写成可复制的项目规则，让助手在编码前暴露不确定性、在编码中保持克制，并用测试与验证闭环替代模糊的「做好就行」。

## 与替代方案

- 相比通用 `CLAUDE.md` 模板或空规则文件，本仓库针对 LLM 编码失误给出了具体原则与自检问题，而非泛泛的「写好代码」。
- 相比 Cursor Rules / Copilot Instructions 的自定义写法，这里提供经过社区验证的完整条文，可直接安装或合并进现有配置。
- 若你需要多代理编排、技能市场或运行时沙箱，可评估同一作者团队的 [Multica](https://github.com/multica-ai/multica)；本仓库专注行为约束，不负责代理调度。

## 适应人群

- 使用 Claude Code 或 Cursor 做日常开发的工程师，希望减少 AI 乱改代码。
- 需要在团队内统一 AI 助手行为规范的 Tech Lead 或平台同学。
- 已遇到「模型过度设计 / 顺手重构 / 不先澄清需求」等痛点的个人开发者。

## 如何使用

### 前置条件

- 使用 Claude Code，或能在项目中放置 `CLAUDE.md` / Cursor 规则的环境。
- 对目标仓库有写入权限（安装插件或追加规则文件）。
- 理解准则偏向「谨慎优于速度」，简单一行修改不必套用全部流程。

### 安装方式

**方式 A：Claude Code 插件（推荐）**

在 Claude Code 内添加 marketplace 并安装：

```
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
```

**方式 B：项目级 CLAUDE.md**

新项目：

```bash
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
```

已有 `CLAUDE.md` 时追加：

```bash
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
```

**方式 C：Cursor**

参考仓库内 [CURSOR.md](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CURSOR.md)，将 `.cursor/rules/karpathy-guidelines.mdc` 复制到目标项目，或安装为全局 Skill。

### 首次运行

安装插件或写入规则后，在 Claude Code / Cursor 中打开目标项目，发起一个中等复杂度的编码任务（如「为某 API 补输入校验」），观察助手是否会在实现前澄清歧义、列出计划与验证步骤。

### 验证是否成功

若准则生效，你应看到：diff 更聚焦请求范围、实现前出现澄清问题、复杂任务附带可验证步骤。可在 `CLAUDE.md` 末尾追加项目专属规则（语言栈、测试要求等）并与本准则合并使用。

### 常见坑 / 注意事项

- README 中的插件 marketplace 与 `CLAUDE.md` 原始地址仍指向 `forrestchang/andrej-karpathy-skills`；与 `multica-ai`  fork 内容同步，安装时以 README 为准。
- 准则会抑制过度工程，对明显的一行修复不必强制完整流程，需结合任务复杂度判断。
- 合并进现有 `CLAUDE.md` 时注意去重，避免与项目既有规则冲突；项目特定约束应写在独立章节中。

---

# Skills for Real Engineers

> Matt Pocock 的可组合 Agent 技能库，用 grilling、领域语言与 TDD 把控真实工程，而非 vibe coding。

- 页面：https://www.niceshare.site/github/skills/
- 仓库：https://github.com/mattpocock/skills
- 语言：Shell
- Stars：178620
- 许可证：MIT
- 标签：AI 编程、Agent、工作流
- 收录：2026-07-20（更新于 2026-07-20）

## 项目介绍

Skills for Real Engineers 是 Matt Pocock 从日常 `.agents` 目录公开的一套 **面向真实工程的 Agent 技能库**。它刻意做成小而可组合、易改写的技能，而不是接管整条研发流程的大型方法论（如 GSD、BMAD、Spec-Kit）。目标是修复 Claude Code、Codex 等编码代理常见的四类失败：需求错位、表述冗长、代码不可靠、架构迅速腐化，让你在保留控制权的前提下，用可重复的工程纪律交付应用。

## 核心特性

- **`/grill-me` / `/grill-with-docs`**：动手前强制「拷问」对齐需求；后者还会沉淀项目领域语言（`CONTEXT.md`）与 ADR
- **反馈闭环技能**：`/tdd`（红绿重构）、`/diagnosing-bugs`（复现 → 假设 → 观测 → 修复）、`/code-review`（规范轴 + 规格轴双审查）
- **架构与规格工具**：`/to-spec`、`/to-tickets`、`/implement`、`/improve-codebase-architecture`、`/wayfinder` 覆盖从规格到大块工作拆解
- **用户触发 vs 模型触发**：用户斜杠命令负责编排；模型可自动调用的技能承载可复用纪律，避免技能互相嵌套失控
- **双安装哲学**：[skills.sh](https://skills.sh/mattpocock/skills) 拷贝进项目可本地改写；Claude Code 插件则以只读托管包跟随上游更新

## 对用户价值

Agent 最常见的问题不是「不会写代码」，而是没对齐就开写、缺少共享术语导致啰嗦、没有测试与调试闭环、以及高速编码加速软件熵增。这套技能把 Pragmatic Programmer、DDD、TDD 与深模块设计等工程基本功压缩成可调用流程：先 grilling 对齐，再建立领域语言，用 TDD/诊断技能保证反馈，用架构技能定期「救泥球」。适合想认真交付产品、又不想把流程主权交给黑盒方法论的人。

## 与替代方案

- 相比 [Superpowers](https://github.com/obra/superpowers) 与 [Agent Skills](https://github.com/addyosmani/agent-skills) 等「完整方法论 / 全生命周期工作流」包，本仓库强调 **小技能可组合、可本地 hack**，明确反对由方法论「拥有」整条流程。
- 相比 [Karpathy Coding Guidelines](https://github.com/multica-ai/andrej-karpathy-skills) 等单文件行为准则，这里提供 **可触发的 grilling、规格、TDD、审查与架构改进技能链**，而不只是编码克制原则。
- 相比 GSD / BMAD / Spec-Kit 一类重流程框架：它们帮你推进过程，但常削弱你对中间步骤与故障排查的控制；本仓库刻意把控制权留在用户与可编辑 skill 文件中。
- 若你需要官方 Agent Skills 规范与跨宿主分发标准，可并行参考 [agentskills.io](https://agentskills.io) / Anthropic skills 生态；本仓库是方法论实践集，不是规范本身。

## 适应人群

- 使用 Claude Code、Codex、Cursor 等 Agent，希望先对齐再写代码的工程师。
- 受够 vibe coding，想把 TDD、领域语言与代码审查嵌回日常 Agent 流程的个人开发者。
- 需要可 fork、可改写技能包，而不是订阅黑盒研发框架的团队与 Tech Lead。

## 如何使用

### 前置条件

- 已安装可运行 Agent Skills 的宿主（Claude Code、Codex，或 skills.sh 支持的其他 harness）。
- Node.js / `npx` 可用（skills.sh 安装路径）；或已安装 Claude Code CLI（插件路径）。
- 每个仓库首次使用前需运行一次 `/setup-matt-pocock-skills` 完成配置。

### 安装方式

**方式 A：skills.sh（可编辑副本，推荐想本地改写时）**

```bash
npx skills@latest add mattpocock/skills
```

安装时选择需要的 skills 与目标 Agent，并确保勾选 `/setup-matt-pocock-skills`。

**方式 B：Claude Code 插件（只读托管、跟随上游更新）**

在 Claude Code 内：

```
/plugin marketplace add mattpocock/skills
/plugin install mattpocock-skills@mattpocock
```

或在 shell：

```bash
claude plugin marketplace add mattpocock/skills
claude plugin install mattpocock-skills@mattpocock
```

### 首次运行

在目标仓库中运行 `/setup-matt-pocock-skills`，按提示选择：

1. Issue tracker（GitHub / Linear / 本地文件）
2. triage 所用标签（供 `/triage` 使用）
3. 文档存放位置（如 `CONTEXT.md`、ADR 目录）

之后对任意变更先跑 `/grill-me` 或 `/grill-with-docs`，再进入规格、实现与审查。

### 验证是否成功

- `/setup-matt-pocock-skills` 能完成问答并写入配置。
- 能调用 `/grill-me`（或 `/grill-with-docs`）并对计划展开追问。
- 工程类技能（如 `/tdd`、`/to-spec`）可在对应场景被触发或手动调用。
- 使用 skills.sh 时，项目内应出现可编辑的 skill 文件；使用插件时，技能以托管包形式可用。

### 常见坑 / 注意事项

- **务必先 setup**：跳过 `/setup-matt-pocock-skills` 时，依赖 issue tracker / 标签 / 文档路径的工程技能可能行为异常。
- **两种安装别混用预期**：skills.sh 适合 fork 改造；插件适合「订阅 Matt 的集合」——本地改插件内容不会持久，也不应指望。
- **Codex 等非 Claude 宿主**：当前通过 skills.sh 安装；原生 Codex 插件仍在路线图上（见仓库 ADR）。
- **grilling 会变慢变深**：这是刻意设计；小改动可酌情缩短，但核心价值就在对齐，不要为了速度完全跳过。
- 技能会随上游演进，关注 [CHANGELOG](https://github.com/mattpocock/skills/blob/main/CHANGELOG.md) 与作者 newsletter。

---

# OpenCode

> 开源 AI 编码 Agent，支持终端、桌面与 IDE，可自由接入 75+ 大模型提供商。

- 页面：https://www.niceshare.site/github/opencode/
- 仓库：https://github.com/anomalyco/opencode
- 官网：https://opencode.ai
- 语言：TypeScript
- Stars：176305
- 许可证：MIT
- 标签：AI 编程、Agent、CLI
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

OpenCode 是由 Anomaly 团队维护的开源 AI 编码 Agent，可在终端 TUI、桌面应用与 IDE 扩展中使用。它基于 AI SDK 与 Models.dev，支持 75+ 大模型提供商及本地模型，内置 Build 与 Plan 双模式，适合从代码探索到跨文件改动的完整开发流程。项目采用 MIT 许可，社区活跃，文档与多语言 README 完善。

## 核心特性

- **多入口形态**：终端 TUI、桌面应用（Beta）与 IDE 扩展，覆盖不同工作习惯
- **Build / Plan 双 Agent**：Tab 切换；Plan 默认只读、改文件与 bash 需确认，Build 具备完整开发权限
- **75+ 模型提供商**：通过 `/connect` 配置 API Key，支持 Anthropic、OpenAI、本地模型等；可选 OpenCode Zen 精选模型列表
- **项目级上下文**：`/init` 分析仓库并生成 `AGENTS.md`，帮助 Agent 理解项目结构与编码规范
- **会话协作**：支持 `/undo`/`redo` 回滚改动、`/share` 分享对话链接，以及 `@general` 子代理处理复杂搜索

## 对用户价值

OpenCode 把「理解代码库」和「执行多步改动」收敛到一个开源 Agent 里，同时保留 Plan 模式的安全边界。相比绑定单一厂商的闭源工具，你可以按任务切换模型与提供商，本地或私有端点也能接入。对于习惯终端工作流、又希望 Agent 能读文件、跑命令、做跨文件重构的开发者，它提供了接近商业产品的体验与 MIT 开源自由度。

## 与替代方案

- 相比 **Claude Code**，OpenCode 完全开源且模型无关，不绑定 Anthropic 账户；Claude Code 则是官方深度集成 Anthropic 生态的产品体验。
- 相比 **Cline**，两者都强调自主 Agent 与终端/IDE 多入口；OpenCode 更突出多提供商切换与 OpenCode Zen 托管模型，Cline 则在 Kanban 并行编排与 SDK 扩展上更突出。
- 相比 **Aider**，OpenCode 自主性更强、界面更完整（TUI/桌面）；Aider 更轻量，适合逐 diff 结对与快速 git 集成。
- 若仅需 IDE 内补全而非 Agent 任务，**Continue** 或 **Copilot** 可能更轻量。

## 适应人群

- 习惯终端或桌面 TUI、希望用自然语言驱动跨文件改动的个人开发者。
- 需要灵活切换大模型提供商、或接入本地/私有模型的团队。
- 想评估开源 Agent 编码工具、对比 Plan/Build 工作流与商业方案的技术决策者。

## 如何使用

### 前置条件

- 现代终端模拟器（如 WezTerm、Ghostty、Kitty 等；桌面版可跳过）。
- 至少一个 LLM 提供商的 API Key，或通过 [OpenCode Zen](https://opencode.ai/auth) 获取托管密钥。
- Node.js 环境（若使用 npm/bun/pnpm/yarn 安装）；Git 管理的项目目录便于回滚改动。

### 安装方式

**推荐（macOS / Linux）：**

```bash
curl -fsSL https://opencode.ai/install | bash
```

**Homebrew（macOS / Linux，推荐 tap 源）：**

```bash
brew install anomalyco/tap/opencode
```

**npm 全局安装：**

```bash
npm i -g opencode-ai@latest
```

**Windows：**

```powershell
scoop install opencode
# 或
choco install opencode
```

**桌面应用（Beta）：** 从 [opencode.ai/download](https://opencode.ai/download) 或 [Releases](https://github.com/anomalyco/opencode/releases) 下载对应平台安装包。

> 安装前请移除 0.1.x 之前的旧版本。更多安装方式见 [官方文档](https://opencode.ai/docs)。

### 首次运行

进入目标项目目录，启动 OpenCode 并连接模型提供商：

```bash
cd /path/to/your-project
opencode
```

在 TUI 中执行 `/connect`，选择 OpenCode Zen 或其他提供商并粘贴 API Key。随后运行 `/init` 生成项目级 `AGENTS.md`。

### 验证是否成功

确认 `opencode` 命令可启动、TUI 能响应输入。用 Plan 模式（Tab 切换）提一个代码探索问题，再切回 Build 模式尝试小改动；执行 `/models` 应能看到已配置的模型列表。

### 常见坑 / 注意事项

- **旧版本冲突**：0.1.x 之前版本需先卸载，否则安装脚本可能异常。
- **Agent 权限**：Build 模式可改文件并执行 bash，首次试用应限制任务范围；Plan 模式虽默认只读，运行命令仍会请求确认。
- **API Key 存储**：密钥保存在 `~/.local/share/opencode/auth.json`，勿提交到版本库。
- **第三方衍生项目**：名称含 "opencode" 的非官方项目（如 opencode-dashboard）与 OpenCode 团队无隶属关系，选用时注意甄别。

---

# Ollama

> 在本机快速下载、运行和管理大语言模型的命令行与服务工具。

- 页面：https://www.niceshare.site/github/ollama/
- 仓库：https://github.com/ollama/ollama
- 官网：https://ollama.com
- 语言：Go
- Stars：174528
- 许可证：MIT
- 标签：本地模型、CLI、AI 工具
- 收录：2026-06-19（更新于 2026-06-19）

## 项目介绍

Ollama 是在本机运行大语言模型的实用工具，提供命令行、后台服务和 OpenAI 兼容 API。它把模型下载、启动和调用压缩到很少的命令里，常被用作 Open WebUI、编辑器插件和自研 AI 应用的本地模型底座。

## 核心特性

- 一条命令拉取并运行主流开源模型（Llama、Qwen、DeepSeek、Gemma 等）
- 提供本地 HTTP API，便于应用与脚本集成
- 支持 macOS、Windows、Linux 与 Docker 部署
- 模型与版本管理简单，适合频繁切换与试验
- 生态包含 Python、JavaScript 等官方客户端库

## 对用户价值

对开发者而言，Ollama 提供稳定的本地模型服务入口，可被聊天界面、编码助手或原型应用直接调用。对普通用户而言，它让「在自己电脑上跑模型」变得可理解、可重复，而不必手动处理权重文件与推理框架。

## 与替代方案

- 相比 LM Studio 等图形化工具，Ollama 更偏命令行与 API，适合集成到自动化流程。
- 相比直接调用 llama.cpp，Ollama 封装了模型管理与分发，上手更快。
- 若需要多卡集群或极致吞吐，应评估 vLLM、TGI 等服务端方案。

## 适应人群

- 想尝试本地大模型的个人用户。
- 需要本地模型 API 的开发者。
- 构建自托管 AI 工具链的团队。

## 如何使用

### 前置条件

- 根据目标模型准备足够内存或显存（7B 模型通常需 8GB+ 内存）。
- macOS / Windows / Linux 任一受支持平台，或已安装 Docker。

### 安装方式

从 [ollama.com](https://ollama.com) 下载对应平台安装包，或使用 Docker：

```bash
docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama
```

### 首次运行

```bash
ollama run llama3.2
```

首次执行会自动拉取模型权重，完成后即可在终端对话或通过 API 调用。

### 验证是否成功

在另一终端执行 `ollama list` 确认模型已安装，或访问 `http://localhost:11434` 检查服务是否响应。

### 常见坑 / 注意事项

- 大模型对内存/显存敏感，选错规格会导致极慢或 OOM。
- 企业环境注意模型许可证与数据出境策略。
- API 默认监听本机，对外暴露时需自行加固网络与访问控制。

---

# Dify

> 面向代理式工作流开发的生产级低代码 LLM 应用平台。

- 页面：https://www.niceshare.site/github/dify/
- 仓库：https://github.com/langgenius/dify
- 官网：https://dify.ai
- 语言：TypeScript
- Stars：145825
- 许可证：Unknown
- 标签：Agent、工作流、低代码
- 收录：2026-06-19（更新于 2026-06-19）

## 项目介绍

Dify 是用于构建代理式 AI 工作流的开源 LLM 应用开发平台，面向从原型到生产的应用交付。它把提示词编排、RAG 知识库、模型管理、工具调用、Agent 能力与可观测性整合进直观的低代码界面，适合产品、运营与工程跨角色协作。

## 核心特性

- 可视化 AI 工作流与 Agent 编排
- 内置 RAG 管道与知识库管理
- 多模型接入与统一 API 发布
- 可观测性集成（Langfuse、Opik、Arize Phoenix 等）
- 支持云服务、社区版自托管与企业部署

## 对用户价值

Dify 降低了非纯工程团队构建 AI 应用的门槛，同时仍保留部署和扩展空间。它特别适合把「一个提示词」扩展成可测试、可迭代、可交付的应用工作流，并在一处管理版本与调用监控。

## 与替代方案

- 相比 n8n 等通用自动化平台，Dify 更专注 LLM 应用与 Agent 场景。
- 相比纯代码框架（LangChain），Dify 提供可视化编排与开箱即用的应用托管。
- 若只需极简聊天机器人且团队全栈工程能力强，自研 + LangGraph 可能更灵活。

## 适应人群

- 希望快速搭建 AI 应用的产品和工程团队。
- 需要知识库、流程和工具集成的企业内部项目。
- 想比较低代码 AI 平台架构的开发者。

## 如何使用

### 前置条件

- 自托管需满足官方最低硬件要求（通常建议 4GB+ 内存，生产环境更高）。
- 已准备至少一个 LLM API 密钥或本地兼容端点。

### 安装方式

社区版常用 Docker Compose 部署，详见 [自托管文档](https://docs.dify.ai/getting-started/install-self-hosted)：

```bash
git clone https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
docker compose up -d
```

### 首次运行

访问本地控制台（默认 `http://localhost/install`），完成初始化并创建首个应用，配置模型与知识库。

### 验证是否成功

运行一个简单聊天或工作流应用，确认模型回复、知识检索与 API 调用均正常。

### 常见坑 / 注意事项

- 生产环境需单独规划数据库、向量库与 HTTPS。
- 上线前评审提示词注入、权限边界与失败分支处理。
- 关注模型调用成本与速率限制，避免工作流循环放大费用。

---

# Open WebUI

> 面向 Ollama 与 OpenAI 兼容 API 的自托管 AI Web 界面，支持 RAG 与多用户协作。

- 页面：https://www.niceshare.site/github/open-webui/
- 仓库：https://github.com/open-webui/open-webui
- 官网：https://openwebui.com
- 语言：Python
- Stars：142246
- 许可证：Unknown
- 标签：本地模型、自托管、AI 工具
- 收录：2026-06-19（更新于 2026-06-19）

## 项目介绍

Open WebUI 是一个功能丰富的自托管 AI Web 平台，常见搭配是 Ollama、本地推理服务或兼容 OpenAI API 的后端。它把对话、模型管理、RAG 知识库和多用户能力打包成可部署应用，适合希望在内网或家用服务器上运行 AI 助手的用户。

## 核心特性

- 响应式 Web 界面，支持桌面与移动端访问
- 原生对接 Ollama 与 OpenAI 兼容 API
- 内置 RAG 管道，可上传文档构建知识库
- 支持多模型切换、对话分支与角色预设
- Docker 一键部署，社区插件与主题生态活跃

## 对用户价值

它把模型调用、对话体验和常见管理能力包装成可部署的 Web 应用，用户不必从零编写聊天前端。对使用 Ollama 或私有 API 的个人与小团队，落地成本明显低于自建全套 UI 与鉴权系统。

## 与替代方案

- 相比 LobeHub 等多模型客户端，Open WebUI 更强调自托管与 RAG 一体化。
- 相比 ChatGPT 等云服务，数据与模型调用留在自己的基础设施内。
- 若只需极简 CLI 对话，Ollama 自带界面或终端工具可能更轻量。

## 适应人群

- 使用 Ollama 或 OpenAI 兼容 API 的个人用户。
- 需要私有 AI 助手入口的小团队。
- 想快速验证本地模型体验的自托管爱好者。

## 如何使用

### 前置条件

- 已安装 Docker，或具备 Python 运行环境。
- 后端模型服务可用（本机 Ollama 或远程兼容 API）。

### 安装方式

Ollama 在本机时，常用 Docker 命令：

```bash
docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:main
```

### 首次运行

浏览器访问 `http://localhost:3000`，按向导创建管理员账号并连接 Ollama 或 API 端点。

### 验证是否成功

发起一次对话并切换模型，确认回复正常；若启用 RAG，上传小文档测试检索是否生效。

### 常见坑 / 注意事项

- Docker 访问宿主机 Ollama 时需正确配置 `host.docker.internal` 或网络模式。
- 多用户场景务必配置认证与 HTTPS，避免内网裸奔。
- 定期备份 `open-webui` 数据卷，避免对话与知识库丢失。

---

# LangChain

> 面向 Agent、RAG 与 LLM 应用编排的 AI 工程平台与框架生态。

- 页面：https://www.niceshare.site/github/langchain/
- 仓库：https://github.com/langchain-ai/langchain
- 官网：https://docs.langchain.com/langchain/
- 语言：Python
- Stars：139697
- 许可证：MIT
- 标签：Agent、RAG、开发框架
- 收录：2026-06-19（更新于 2026-06-19）

## 项目介绍

LangChain 是围绕 LLM 应用开发形成的框架与平台生态，覆盖模型调用、工具使用、检索增强生成、Agent 流程与可观测性。它帮助开发者用可互操作的组件与第三方集成，把原型 AI 应用推进到更结构化的工程实现。

## 核心特性

- **LangChain**：高层组件与集成，快速拼装 LLM 应用
- **LangGraph**：低层 Agent 编排，适合复杂、有状态工作流
- **Deep Agents**：内置规划、子代理与文件系统等常见 Agent 模式
- 丰富的模型、向量库与工具集成
- **LangSmith**：评测、可观测性与调试平台

## 对用户价值

LangChain 的价值在于抽象与生态：开发者可以用统一接口接入模型、向量检索、工具和工作流组件，减少重复胶水代码。对团队来说，它也提供了讨论 LLM 应用架构时较通用的词汇与参考实现。

## 与替代方案

- 相比 LlamaIndex，LangChain 更强调 Agent 编排与全栈平台（含 LangSmith）。
- 相比自研胶水代码，框架降低入门成本，但复杂场景需理解抽象层与版本迁移。
- 若团队偏可视化低代码，Dify、Flowise 等可能更快落地。

## 适应人群

- 正在构建 RAG、Agent 或 LLM 应用的开发者。
- 想学习 AI 应用工程化模式的技术团队。
- 需要在多模型、多工具之间做编排的产品原型团队。

## 如何使用

### 前置条件

- Python 3.9+（或按文档使用 JavaScript/TypeScript 生态）。
- 目标 LLM 的 API 密钥或本地端点。

### 安装方式

```bash
pip install -U langchain langchain-openai
```

按所用模型与集成安装对应包（见 [官方安装指南](https://python.langchain.com/docs/get_started/installation)）。

### 首次运行

跟随文档实现一个最小 RAG 或工具调用 Agent，例如文档问答或带搜索的问答链。

### 验证是否成功

确认链路能完成检索/工具调用并返回合理答案；若接入 LangSmith，可在控制台看到 trace。

### 常见坑 / 注意事项

- 版本迭代较快，生产项目应锁定依赖并阅读迁移指南。
- Agent 循环可能放大 token 成本，需设置步数与超时限制。
- 生产环境重点评估错误处理、权限隔离与数据合规。

---

# Claude Code

> Anthropic 官方终端 Agent 编码工具，自然语言理解代码库并驱动编辑与 Git 工作流。

- 页面：https://www.niceshare.site/github/claude-code/
- 仓库：https://github.com/anthropics/claude-code
- 官网：https://code.claude.com/docs/en/overview
- 语言：Python
- Stars：133329
- 许可证：Unknown
- 标签：AI 编程、Agent、CLI
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Claude Code 是 Anthropic 推出的 Agent 编码工具，可在终端、IDE 与 GitHub（@claude）中使用。它读取本地代码库上下文，通过自然语言完成跨文件编辑、复杂代码解释、常规开发任务与 Git 工作流。本仓库主要承载官方插件、示例与问题反馈入口；CLI 本体需通过官方安装脚本获取，并绑定 Anthropic 账户使用。

## 核心特性

- **终端原生 Agent**：在项目目录运行 `claude`，用对话驱动读文件、改代码、跑命令
- **多入口集成**：支持终端 CLI、IDE 扩展，以及在 GitHub 上 @claude 触发协作
- **Git 工作流**：可协助提交、分支与 PR 相关操作，减少重复性版本管理步骤
- **官方插件生态**：仓库 `plugins/` 提供 code-review、feature-dev、security-guidance、hookify 等扩展命令与代理
- **内置反馈通道**：终端内 `/bug` 可直接上报问题，社区可通过 Discord 交流

## 对用户价值

Claude Code 把「理解整个仓库」和「执行多步改动」收敛到一个 Agent 流程里，比 Web 聊天复制粘贴更高效。对于已使用 Claude 的开发者，它提供与 Anthropic 模型深度对齐的官方编码体验；插件与 Hooks 机制也便于团队把代码审查、安全规范等流程固化进日常开发。

## 与替代方案

- 相比 **Cline** 等开源自主代理，Claude Code 是 Anthropic 官方产品，模型与产品迭代绑定更紧，但核心 CLI 并非传统意义上的全开源软件。
- 相比 **Aider**，Claude Code 自主性更强，可编排终端与多文件任务；Aider 更强调逐 diff 结对与多模型切换灵活性。
- 相比 **Cursor** 等 IDE Agent，Claude Code 更偏终端与 GitHub 工作流；若团队已 All-in 某一 IDE，可评估是否需额外引入 CLI Agent。
- 若仅需补全而非 Agent 任务，**Continue** 或 **Copilot** 可能更轻量。

## 适应人群

- 已订阅 Claude Pro/Max 或企业方案、希望把 Agent 接入日常编码的开发者。
- 习惯终端与 Git 工作流、需要跨文件自动化改动的个人或小团队。
- 想在 GitHub PR 或 IDE 中与官方 Claude Agent 协作的工程师。

## 如何使用

### 前置条件

- Node.js 18+ 运行环境（官方 README 标注；安装脚本会处理依赖）。
- 有效的 Anthropic 账户与 Claude Code 使用权限。
- 建议在已有 Git 管理的项目目录中试用，便于回滚改动。

### 安装方式

> npm 全局安装已标记为 deprecated，请优先使用官方推荐方式。

**macOS / Linux（推荐）：**

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

**Homebrew（macOS / Linux）：**

```bash
brew install --cask claude-code
```

**Windows（推荐）：**

```powershell
irm https://claude.ai/install.ps1 | iex
```

**WinGet（Windows）：**

```powershell
winget install Anthropic.ClaudeCode
```

更多安装选项、卸载与排错见 [官方 Setup 文档](https://code.claude.com/docs/en/setup)。

### 首次运行

进入目标项目目录，执行：

```bash
claude
```

用自然语言描述一个小任务（如补充测试、解释某模块或整理 Git 提交），观察 Agent 如何读取文件并提出改动。

### 验证是否成功

确认 `claude` 命令可启动、能访问项目文件，且对话中可触发读/写与 Git 相关操作。若使用插件，可在仓库 [plugins 目录](https://github.com/anthropics/claude-code/tree/main/plugins) 查阅可用扩展并按文档启用。

### 常见坑 / 注意事项

- **勿再用 deprecated 的 `npm install -g @anthropic-ai/claude-code`**，除非临时过渡；官方已推荐脚本或包管理器安装。
- 使用前阅读 [数据使用政策](https://code.claude.com/docs/en/data-usage)，了解会话与反馈数据的收集范围。
- Agent 可执行终端命令，首次试用应限制任务范围并审查高风险操作。
- 本 GitHub 仓库以插件与反馈为主，遇到产品问题可用 `/bug` 或提交 [GitHub Issue](https://github.com/anthropics/claude-code/issues)。

---

# Clash Verge Rev

> 基于 Tauri 2 的跨平台 Clash Meta (mihomo) 图形客户端，延续 Clash Verge 生态，支持系统代理与 TUN。

- 页面：https://www.niceshare.site/github/clash-verge-rev/
- 仓库：https://github.com/clash-verge-rev/clash-verge-rev
- 官网：https://www.clashverge.dev
- 语言：TypeScript
- Stars：126677
- 许可证：GPL-3.0
- 标签：开发工具、桌面应用、网络工具
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

[Clash Verge Rev](https://www.clashverge.dev) 是原 [Clash Verge](https://github.com/zzzgydi/clash-verge) 的社区延续版，基于 Rust 与 Tauri 2 构建，内置 [mihomo (Clash.Meta)](https://github.com/MetaCubeX/mihomo) 内核，面向 Windows、macOS 与 Linux 提供统一的代理管理界面。它在保留 Clash 规则分流能力的同时，把配置编辑、系统代理守卫、TUN 虚拟网卡与主题定制收进一款轻量桌面应用，适合不愿长期手写 YAML 却仍想精细控制路由策略的用户。

## 核心特性

- **Tauri 2 + mihomo 内核**：Rust 后端与 Web 前端结合，内置 Clash.Meta 内核，并可切换 Alpha 版本内核
- **可视化配置管理**：支持 Merge / Script 增强、语法提示，以及节点与规则的可视化编辑
- **系统级接管**：系统代理与代理守卫、TUN（虚拟网卡）模式，适配全局或分应用分流场景
- **界面与主题定制**：明暗主题、自定义主题色、代理组/托盘图标，以及 CSS Injection
- **配置备份同步**：通过 WebDAV 备份与同步配置文件，便于多设备迁移
- **多语言与文档**：简体中文、English 等七种语言 README；[官方文档站](https://clash-verge-rev.github.io/) 覆盖安装与 FAQ

## 对用户价值

Clash 系工具功能强大，但纯命令行或简陋 GUI 往往让「导入订阅 → 选节点 → 开 TUN → 调规则」变成反复改 YAML 的体力活。Clash Verge Rev 把高频操作图形化：托盘一键切换、规则/节点面板直编、Merge 与 Script 在不破坏原配置的前提下叠加策略。对个人用户，它降低从 Clash for Windows 或停更版 Clash Verge 迁移的学习成本；对进阶用户，WebDAV 同步与内核版本切换让实验新特性与多机保持一致更省事。GPL-3.0 开源且社区活跃（12 万+ Star），适合希望客户端可控、可审计的长期使用者。

## 与替代方案

- 相比 **[Clash for Windows](https://github.com/Fndroid/clash_for_windows_pkg)**（已停更），Clash Verge Rev 基于 Tauri 2 持续维护，内置 mihomo 内核，跨平台覆盖 Win / macOS / Linux，并延续 Verge 系的 Merge、Script 与主题定制能力。
- 相比原 **[zzzgydi/clash-verge](https://github.com/zzzgydi/clash-verge)**，Rev 为社区接力版本，修复与功能迭代更活跃；界面与配置思路相近，老用户迁移成本较低。
- 相比 **[ClashX Pro](https://github.com/yichengchen/clashX)**、**[ClashX.Meta](https://github.com/MetaCubeX/ClashX.Meta)** 等 **macOS 专用客户端**，Clash Verge Rev 强调三端一致体验，适合同时使用 Windows 与 macOS 的用户。
- 相比 **[sing-box](https://github.com/SagerNet/sing-box)** 系 GUI（如 SFM、GUI.for.SingBox），Clash Verge Rev 绑定 Clash/Meta 配置与规则语法；若你已有大量 Clash 订阅与规则，无需重写配置链。
- 相比 **纯 mihomo 命令行**，GUI 提供系统代理守卫、托盘切换与可视化编辑；若只需 headless 网关或服务器侧转发，命令行或 Docker 方案更轻。

## 适应人群

- 从 Clash for Windows 或停更 Clash Verge 迁移、需要现代跨平台 GUI 的代理用户。
- 希望可视化编辑节点与规则、使用 TUN/系统代理守卫的进阶玩家。
- 需要在多台设备间通过 WebDAV 同步 Clash 配置、并愿意跟进社区版迭代的长期使用者。

## 如何使用

### 前置条件

- **Windows**：x64 或 x86
- **macOS**：11 及以上（Intel 或 Apple Silicon）
- **Linux**：x64 或 arm64 的主流发行版
- 自备合法可用的代理订阅或配置文件（Clash / Meta 格式）；客户端本身不提供节点服务

### 安装方式

从 [GitHub Releases](https://github.com/clash-verge-rev/clash-verge-rev/releases) 下载对应平台安装包：

| 版本 | 说明 |
| :--- | :--- |
| **Stable** | 正式版，适合日常使用（推荐） |
| **AutoBuild** | 滚动构建，适合尝鲜反馈，可能存在缺陷 |
| **Alpha** | 已废弃，仅作发布流程测试 |

平台支持：Windows (x64/x86)、Linux (x64/arm64)、macOS 11+ (Intel/Apple)。

详细安装步骤与常见问题见 [官方文档](https://clash-verge-rev.github.io/)。

### 首次运行

1. 安装并启动 Clash Verge Rev。
2. 在配置页**导入订阅链接**或本地 YAML 配置文件。
3. 在代理页选择节点或策略组；按需开启**系统代理**或 **TUN 模式**（TUN 通常需管理员/root 权限）。
4. 可选：在设置中配置 Merge/Script 增强、主题与 WebDAV 备份。

### 验证是否成功

- 托盘图标显示已连接，系统代理或 TUN 状态为开启（若你启用了对应模式）。
- 浏览器访问 [ip.sb](https://ip.sb) 或同类检测页，确认出口 IP 与所选节点一致。
- 在应用内查看连接日志/规则命中，确认分流符合预期。
- 若启用 WebDAV，执行一次备份后检查远端是否出现配置文件。

### 常见坑 / 注意事项

- **TUN 无法启动**：Windows 需安装虚拟网卡驱动并以管理员运行；macOS/Linux 需相应权限，详见 [文档 FAQ](https://clash-verge-rev.github.io/faq/windows.html)。
- **订阅导入失败**：检查链接是否有效、格式是否为 Clash Meta 兼容；部分机场需手动更新 User-Agent 或转换订阅。
- **规则不生效**：确认未与其他代理客户端（如 CFW 残留服务）冲突；切换内核版本后建议重启应用。
- **AutoBuild 稳定性**：日常主力环境请优先 Stable；AutoBuild 仅建议测试环境使用。
- **许可证**：GPL-3.0 开源；二次分发或修改衍生版本需遵守 GPL 义务。

---

# Agency Agents

> 收录 230+ 个带人格的 AI 专家角色，可一键安装到 Cursor、Claude Code 等十余种 Agent 工具。

- 页面：https://www.niceshare.site/github/agency-agents/
- 仓库：https://github.com/msitarzewski/agency-agents
- 官网：https://agencyagents.app
- 语言：Shell
- Stars：125262
- 许可证：MIT
- 标签：Agent、AI 编程、开发工具
- 收录：2026-07-03（更新于 2026-07-03）

## 项目介绍

**Agency Agents**（The Agency）是一个持续扩充的 AI 专家角色库，源自 Reddit 社区讨论并经多轮实战打磨。仓库收录 **16 个事业部、230+ 位代理**，每位代理都有独立人格、工作流程、可交付物与成功指标——从 React 前端工程师到 Reddit 社区运营、从「趣味注入师」到「现实检验员」，覆盖工程、设计、营销、销售、付费投放、安全等完整职能谱系。配套桌面应用 [agencyagents.app](https://agencyagents.app) 与 `install.sh` 脚本，可将同一套角色一键分发到 Claude Code、Cursor、Codex、Gemini CLI、OpenCode 等十余种 Agent 宿主。

## 核心特性

- **职能专精**：每位代理深耕单一领域，附带具体流程、代码示例与可衡量产出，而非泛泛的 prompt 模板
- **人格驱动**：独立语气、沟通风格与决策偏好，让 Agent 在对话中保持角色一致性
- **16 事业部编排**：工程、设计、营销、销售、付费媒体、安全、产品、运营等分工明确，可按团队按需选取
- **多宿主一键安装**：`convert.sh` 生成各工具格式，`install.sh` 交互式检测已安装工具并写入对应目录（`.cursor/rules`、`~/.claude/agents/` 等）
- **按需裁剪**：支持 `--division` 按事业部、`--agent` 按单个角色安装，避免一次性灌入全部 230+ 代理
- **原生桌面应用**：macOS / Linux / Windows 图形化浏览名册、安装与自动更新，无需 clone 仓库

## 对用户价值

通用 AI 助手擅长回答问题，却难以稳定扮演「资深 SRE」「PPC 投放策略师」或「代码审查员」等具体岗位。Agency Agents 把岗位知识、交付标准与沟通方式封装成可版本化、可安装的代理文件，让你在 Cursor 或 Claude Code 中直接「召唤」对应专家，减少每次从零写 system prompt 的重复劳动。对个人开发者，它是开箱即用的角色 playbook；对团队，它提供可共享的 Agent 人设标准，让不同成员获得一致的协作体验。

## 与替代方案

- 相比 [Superpowers](https://github.com/obra/superpowers) 等**方法论技能库**，本仓库侧重**按职能划分的人格化专家角色**（工程、营销、销售等），而非 TDD / 子代理编排等研发流程。
- 相比 [Anthropic Skills](https://github.com/anthropics/skills) 等**官方技能规范实现**，Agency Agents 提供更大规模的**跨职能角色名册**，并内置 Cursor、Codex、OpenCode 等多宿主格式转换。
- 相比手写 Cursor Rules 或 `CLAUDE.md`，这里每位代理是**独立 Markdown 文件**，可按岗位组合安装，且附带桌面应用降低分发门槛。
- 角色内容来自社区共创，**质量与适用场景因代理而异**；生产环境建议先小范围试用，再纳入主力工具链。

## 适应人群

- 使用 Cursor、Claude Code、Codex 等工具，希望按职能切换 Agent 人设的开发者与独立创作者。
- 需要营销、销售、设计等非工程类 AI 协作角色的中小团队或一人公司。
- 已厌倦通用 prompt 模板、想从成熟角色库中挑选、裁剪并快速部署的 Agent 效率型用户。

## 如何使用

### 前置条件

- 至少安装一种 README 支持的 Agent 宿主（Cursor、Claude Code、Codex、Gemini CLI、OpenCode 等）。
- 使用脚本安装时需 clone 仓库并具备 Bash 环境；macOS 用户也可直接安装桌面应用。
- OpenCode 用户注意：运行时目前仅注册约 119 个代理，超出部分会被静默丢弃，建议用 `--division` 按需安装。

### 安装方式

**方式一：桌面应用（推荐）**

从 [agencyagents.app](https://agencyagents.app) 或 [GitHub Releases](https://github.com/msitarzewski/agency-agents-app/releases/latest) 下载。macOS 也可：

```bash
brew install --cask msitarzewski/agency-agents/agency-agents
```

**方式二：脚本安装（需 clone 仓库）**

```bash
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents
./scripts/convert.sh
./scripts/install.sh
```

指定工具与事业部：

```bash
./scripts/install.sh --tool cursor --division engineering,design
./scripts/install.sh --tool claude-code --agent frontend-developer,ui-designer
./scripts/install.sh --list teams
```

### 首次运行

桌面应用：打开后浏览名册，勾选目标代理与宿主工具，点击安装。脚本方式：运行 `install.sh` 后在交互界面勾选已检测到的工具，确认安装路径后写入。在 Cursor 中可在对话里引用已安装规则，例如「以前端开发者模式帮我实现一个 React 组件」。

### 验证是否成功

- Cursor：检查项目或用户目录下 `.cursor/rules/` 是否出现对应 `.mdc` 文件。
- Claude Code：确认 `~/.claude/agents/` 下有目标 `.md` 代理文件。
- 在宿主中激活一位代理，观察其是否按角色人格与交付物格式响应。

### 常见坑 / 注意事项

- 全量安装 230+ 代理可能让宿主加载变慢或触发上限（尤其 OpenCode）；优先用 `--division` 或 `--agent` 按需选取。
- `convert.sh` 与 `install.sh` 支持 `--parallel` 加速，但输出顺序可能不稳定，CI 场景建议去掉该参数。
- 代理内容为社区贡献的参考 playbook，**不保证适配你的具体业务**；敏感场景需人工审核输出。
- 桌面应用与脚本安装的是同一套代理；已有手动定制规则时注意备份，避免覆盖。

---

# Electron

> 基于 Node.js 与 Chromium 的跨平台桌面应用框架，用 Web 技术构建 macOS、Windows 与 Linux 原生应用。

- 页面：https://www.niceshare.site/github/electron/
- 仓库：https://github.com/electron/electron
- 官网：https://electronjs.org
- 语言：C++
- Stars：121684
- 许可证：MIT
- 标签：开发工具、桌面应用、跨平台
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Electron 是 OpenJS Foundation 维护的跨平台桌面应用框架，将 [Node.js](https://nodejs.org/) 与 [Chromium](https://www.chromium.org) 结合，让你用 JavaScript、HTML 和 CSS 编写可在 macOS、Windows、Linux 上运行的桌面程序。Visual Studio Code、Slack、Discord 等知名产品均基于 Electron 构建。本仓库为 Electron 核心源码；日常开发通常通过 npm 安装 `electron` 包，文档与教程见 [electronjs.org](https://electronjs.org/docs)。

## 核心特性

- **Web 技术栈开发桌面应用**：沿用前端技能与生态，主进程/渲染进程模型清晰，可访问 Node.js API 与浏览器能力
- **跨平台二进制分发**：每个版本提供 macOS（Intel / Apple Silicon）、Windows（ia32 / x64 / arm64）与 Linux 预构建包
- **成熟文档与社区**：官方文档覆盖 Quick Start、安全指南、打包发布；[Electron Fiddle](https://github.com/electron/fiddle) 可快速试验 API 与版本
- **可编程调用**：在 Node 脚本中 `require('electron')` 获取二进制路径，便于自动化测试与 CI 集成
- **版本化发布策略**：遵循 [Electron 版本管理](https://www.electronjs.org/docs/latest/tutorial/electron-versioning) 与 Chromium 升级节奏，便于企业级应用规划升级窗口

## 对用户价值

若团队已有 Web 前端能力，Electron 可显著降低桌面客户端的启动成本，避免为每个平台单独维护原生 UI 栈。Chromium 渲染层保证 CSS/Canvas/WebGL 等能力一致，Node.js 侧便于对接文件系统、本地进程与现有 npm 生态。对于需要快速迭代、跨平台一致体验的工具类产品（编辑器、IM、协作软件），Electron 是经过大量生产验证的路径；代价是安装包体积与内存占用通常高于原生方案，需在选型阶段权衡。

## 与替代方案

- 相比 [Tauri](https://tauri.app/)，Electron 生态更成熟、第三方集成与招聘市场更广，但包体积与内存占用通常更大；Tauri 用 Rust 后端 + 系统 WebView，更轻量，适合对体积敏感的新项目。
- 相比 [NW.js](https://nwjs.io/)（原 node-webkit），两者思路相近；Electron 社区规模、文档与主流 IDE/工具链支持更占优，NW.js 在部分遗留项目仍有使用。
- 相比 Flutter Desktop / Qt 等原生 UI 框架，Electron 复用 Web 技能与组件库，开发效率高；原生框架在性能、系统集成与包体积上通常更优，但跨端 UI 与团队技能迁移成本更高。
- 边界说明：本仓库是 **Electron 核心源码**；应用开发安装 npm 包即可，勿将 clone 本 repo 等同于「开始使用 Electron」。贡献源码需阅读 [CONTRIBUTING.md](https://github.com/electron/electron/blob/main/CONTRIBUTING.md)。

## 适应人群

- 希望用 React/Vue/Svelte 等 Web 技术栈交付 macOS、Windows、Linux 桌面客户端的前端或全栈工程师。
- 评估 VS Code、Slack 类产品技术路线，或维护现有 Electron 应用升级与安全策略的技术负责人。
- 需要快速验证桌面 API（窗口、菜单、Tray、原生对话框）的原型团队，可配合 Electron Fiddle 降低试错成本。

## 如何使用

### 前置条件

- Node.js 与 npm（或 pnpm、Yarn），版本以 [官方安装文档](https://www.electronjs.org/docs/latest/tutorial/installation) 为准。
- 目标平台：macOS Ventura+、Windows 10+、或 Ubuntu 18.04+ / Fedora 32+ / Debian 10+ 等受支持 Linux 发行版。
- 中国大陆网络环境若下载二进制缓慢，可配置 [npmmirror 镜像](https://npmmirror.com/mirrors/electron/)。

### 安装方式

**方式一：在项目中安装 Electron（常规应用开发）**

```sh
npm install electron --save-dev
```

**方式二：在 Node 脚本中获取 Electron 二进制路径**

```javascript
const electron = require('electron')
const proc = require('node:child_process')

console.log(electron) // 打印 Electron 可执行文件路径
const child = proc.spawn(electron)
```

更多安装选项、版本管理与镜像配置见 [Installation](https://www.electronjs.org/docs/latest/tutorial/installation) 与 [Electron versioning](https://www.electronjs.org/docs/latest/tutorial/electron-versioning)。

### 首次运行

1. 新建项目目录并安装依赖（见上）。
2. 创建 `main.js` 作为**主进程**入口，创建 BrowserWindow 加载 HTML 页面。
3. 在 `package.json` 中设置 `"main": "main.js"`，通过 `npx electron .` 启动。

最小示例（摘自官方 Quick Start 思路）：

```javascript
// main.js
const { app, BrowserWindow } = require('electron')

function createWindow() {
  const win = new BrowserWindow({ width: 800, height: 600 })
  win.loadFile('index.html')
}

app.whenReady().then(createWindow)
```

也可使用 [Electron Fiddle](https://github.com/electron/fiddle) 零配置试验 API 与不同 Electron 版本。

### 验证是否成功

- 运行 `npx electron .` 后应弹出应用窗口，无阻塞性控制台报错。
- 修改 `index.html` 或渲染进程脚本，重启后界面应反映变更。
- 查阅 [官方文档 Quick Start](https://www.electronjs.org/docs/latest/tutorial/quick-start) 完成主进程/渲染进程/预加载脚本的基本结构验证。

### 常见坑 / 注意事项

- **源码仓库 vs npm 包**：日常开发安装 `electron` 即可；clone 本仓库用于贡献或与 Chromium 同步相关的底层开发，构建流程复杂，见 CONTRIBUTING。
- **安全模型**：启用 `nodeIntegration`、禁用 `contextIsolation` 等旧模式存在 XSS 风险；新项目应遵循 [Security](https://www.electronjs.org/docs/latest/tutorial/security) 指南，通过 preload 暴露最小 API。
- **包体积与内存**：Chromium + Node 带来较大安装包与运行时占用；若产品对体积敏感，可评估 Tauri 等替代方案。
- **版本升级**：Electron 大版本随 Chromium 升级可能移除旧 OS 支持（如 Electron 23 起不再支持 Windows 7/8/8.1）；升级前阅读 [Release Notes](https://www.electronjs.org/blog) 与 CHANGELOG。
- **打包发布**：开发依赖安装不等于可分发的安装包；生产发布需配合 [electron-builder](https://www.electron.build/) 或 [electron-forge](https://www.electronforge.io/) 等工具，并处理代码签名与自动更新策略。

---

# Node.js

> 开源跨平台 JavaScript 运行时，基于 V8 引擎，支撑服务端、CLI 工具与 npm 生态的核心基础设施。

- 页面：https://www.niceshare.site/github/node/
- 仓库：https://github.com/nodejs/node
- 官网：https://nodejs.org
- 语言：JavaScript
- Stars：117874
- 许可证：MIT
- 标签：开发工具、后端、CLI
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Node.js 是 OpenJS Foundation 维护的开源、跨平台 JavaScript 运行时，将 Google V8 引擎与 libuv 事件循环结合，让 JavaScript 可在服务端执行 I/O 密集型任务。它是 npm 生态的基石，支撑着 Express、Next.js、Electron 等大量框架与工具。本仓库为 Node.js **核心源码**；日常开发通常从 [nodejs.org](https://nodejs.org/) 安装二进制，文档与教程亦以官网为准。

## 核心特性

- **跨平台运行时**：官方提供 macOS、Windows、Linux 安装包与二进制，同一套 JavaScript 代码可在多平台部署
- **事件驱动与非阻塞 I/O**：基于 libuv 的高并发模型，适合 API 服务、实时应用与 CLI 工具
- **成熟发布节奏**：Current 每 6 个月发大版本；偶数大版本转 LTS，提供 Active LTS（12 个月）与 Maintenance（18 个月）支持
- **内置 npm 与丰富标准库**：`fs`、`http`、`crypto`、`worker_threads` 等模块覆盖常见服务端场景
- **开放治理**：TSC 技术指导委员会与协作者体系透明运作，安全响应与发布流程规范（见 [GOVERNANCE.md](https://github.com/nodejs/node/blob/main/GOVERNANCE.md)）

## 对用户价值

若你需要用 JavaScript 构建后端 API、自动化脚本、构建工具或桌面应用（配合 Electron），Node.js 是最主流、生态最完整的选择。LTS 版本为企业提供可预期的升级窗口与安全补丁节奏；npm 注册表则让依赖管理与工具链集成成本极低。对于全栈团队，前后端共用语言可降低协作门槛；代价是 CPU 密集任务需借助 Worker Threads、子进程或原生扩展，单线程事件循环模型需在架构设计时留意。

## 与替代方案

- 相比 [Deno](https://deno.com/)，Node.js 生态规模、第三方包数量与招聘市场显著更大；Deno 默认更安全（权限模型）、原生 TypeScript 支持更好，适合 greenfield 项目或对安全沙箱有强需求场景。
- 相比 [Bun](https://bun.sh/)，Node.js 稳定性与 LTS 承诺经过更长生产验证；Bun 在启动速度、包管理一体化方面更快，但生态兼容性与企业级支持仍在追赶。
- 相比 Python / Go / Java 等服务端语言，Node.js 复用前端 JavaScript 技能与 npm 工具链，适合 I/O 密集与实时场景；CPU 密集计算、强类型系统需求或特定企业中间件生态可能更适合其他语言。
- 边界说明：本仓库用于**贡献 Node 核心**或从源码构建；应用开发安装官方二进制或版本管理器即可，无需 clone 本 repo。

## 适应人群

- 用 JavaScript/TypeScript 构建 API、BFF、微服务或 Serverless 函数的后端与全栈工程师。
- 维护 npm 包、CLI 工具、前端构建链（Vite、Webpack 等）或需锁定 LTS 版本的企业技术负责人。
- 希望深入 V8、libuv、模块加载器或参与 Node 核心贡献的系统级开发者（需阅读 [BUILDING.md](https://github.com/nodejs/node/blob/main/BUILDING.md)）。

## 如何使用

### 前置条件

- 操作系统：macOS、Windows 10+、或主流 Linux 发行版（完整支持列表见 [BUILDING.md](https://github.com/nodejs/node/blob/main/BUILDING.md)）。
- 生产环境建议选用 **LTS** 版本；实验性功能使用 Current，Nightly 仅用于测试。
- 从源码构建需安装对应平台的编译工具链（Python、C/C++ 编译器等），复杂度远高于安装官方二进制。

### 安装方式

**方式一：官网安装包（推荐大多数用户）**

从 [nodejs.org/en/download](https://nodejs.org/en/download/) 下载对应平台的 LTS 安装包或二进制。

**方式二：版本管理器（多版本切换）**

```bash
# nvm（macOS / Linux）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts
nvm use --lts
```

```bash
# Homebrew（macOS）
brew install node
```

```bash
# fnm（跨平台，速度快）
curl -fsSL https://fnm.vercel.app/install | bash
fnm install --lts
fnm use lts-latest
```

更多安装选项与包管理器索引见 [nodejs.org 下载页](https://nodejs.org/en/download/package-manager)。

### 首次运行

```bash
node -v
npm -v
node -e "console.log('Hello, Node.js')"
```

创建 `hello.mjs` 并运行：

```javascript
// hello.mjs
console.log(`Node.js ${process.version} on ${process.platform}`);
```

```bash
node hello.mjs
```

### 验证是否成功

- `node -v` 输出预期版本号（生产环境应为 LTS，如 `v22.x` 或当前 LTS 线）。
- `npm -v` 可正常输出版本，无权限或路径错误。
- 运行 `node -e "console.log('ok')"` 输出 `ok`，无模块加载或动态链接错误。
- 查阅 [API 文档](https://nodejs.org/api/) 确认版本与本地安装一致。

### 常见坑 / 注意事项

- **Current vs LTS**：偶数大版本（如 20、22）为 LTS 线，企业生产应优先 LTS；Current 每 6 个月可能引入破坏性变更。
- **源码仓库 vs 日常使用**：clone 本 repo 不等于「安装 Node」；贡献者需遵循 [CONTRIBUTING.md](https://github.com/nodejs/node/blob/main/CONTRIBUTING.md)，构建流程复杂。
- **原生模块编译**：`node-gyp` 类依赖在 Windows 需 Visual Studio Build Tools，macOS 需 Xcode CLI，Linux 需 `build-essential`。
- **ESM 与 CommonJS**：`"type": "module"` 与 `.mjs`/`.cjs` 扩展名影响 `import`/`require` 行为，混用时注意 [模块文档](https://nodejs.org/api/esm.html)。
- **中国大陆网络**：npm 安装缓慢可配置镜像（如 [npmmirror](https://npmmirror.com/)）；Node 二进制亦可使用国内镜像站加速下载。

---

# Rust

> 系统级编程语言，以所有权模型实现内存与线程安全，兼顾高性能与可靠交付。

- 页面：https://www.niceshare.site/github/rust/
- 仓库：https://github.com/rust-lang/rust
- 官网：https://www.rust-lang.org
- 语言：Rust
- Stars：113976
- 许可证：Apache-2.0
- 标签：开发工具、系统编程、后端
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Rust 是由 [Rust Foundation](https://rustfoundation.org/) 与社区维护的开源系统级编程语言，目标是在不牺牲性能的前提下，通过所有权（ownership）与借用检查（borrow checker）在编译期消除内存与数据竞争问题。本仓库为 Rust **编译器（rustc）、标准库与官方文档** 的主源码库；日常开发通常通过 [rustup](https://rustup.rs/) 安装工具链，学习路径与发布节奏以 [rust-lang.org](https://www.rust-lang.org/) 为准。

## 核心特性

- **高性能与低开销**：零成本抽象、无 GC，适合关键服务、嵌入式与需与其他语言 FFI 集成的场景
- **编译期内存与线程安全**：丰富类型系统 + 所有权模型，在编译期捕获空指针、悬垂引用与数据竞争
- **完整工具链**：包管理与构建工具 [Cargo](https://github.com/rust-lang/cargo)、格式化 [rustfmt](https://github.com/rust-lang/rustfmt)、静态分析 [Clippy](https://github.com/rust-lang/rust-clippy)、IDE 支持 [rust-analyzer](https://github.com/rust-lang/rust-analyzer)
- **稳定发布节奏**：6 周一个稳定版（Stable），Beta/Nightly 通道供尝鲜与贡献；Edition 机制平滑语言演进
- **开放治理**：RFC 流程透明，[rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/) 详述编译器架构与贡献路径

## 对用户价值

若你需要在 C/C++ 的性能区间内获得更强的内存安全保证，或构建 CLI、Web 后端、区块链节点、浏览器引擎、游戏引擎与嵌入式固件，Rust 是当前主流且生态快速增长的选项。Cargo 与 crates.io 让依赖管理与跨平台构建成本极低；编译器诊断与文档质量高，降低系统编程入门门槛。代价是学习曲线（所有权与生命周期）与部分场景下编译时间；团队需预留 onboarding 与 CI 缓存策略。

## 与替代方案

- 相比 **C/C++**，Rust 在默认路径上消除大量内存安全类 bug，标准库与包生态更现代；C/C++ 在遗留代码库、特定硬件 SDK 与极致底层控制上仍占主导，迁移存量项目成本较高。
- 相比 **[Go](https://go.dev/)**，Rust 提供更细粒度的性能与内存控制、无 GC 停顿，适合系统组件与嵌入式；Go 上手更快、并发模型简单，适合网络服务与快速迭代的云原生业务。
- 相比 **[Zig](https://ziglang.org/)**，Rust 生态（crates.io、async 运行时、WebAssembly 工具链）更成熟；Zig 强调 C 互操作与编译器简洁，适合追求极简工具链的 greenfield 系统项目。
- 相比 **Java / C#**，Rust 无运行时与 GC，二进制部署轻量，适合基础设施与性能敏感组件；企业级框架、ORM 与托管生态仍更偏向 JVM / .NET 栈。
- 边界说明：本仓库用于**贡献 Rust 编译器/标准库**或从源码构建；应用开发安装 rustup 即可，无需 clone 本 repo。

## 适应人群

- 构建 CLI、API 服务、区块链节点、数据库引擎或 WebAssembly 模块，需要性能与安全兼顾的后端与系统工程师。
- 维护嵌入式、IoT、操作系统组件或需与 C 库 FFI 集成的底层开发者。
- 希望深入编译器、LLVM 后端、语言设计或参与 Rust 核心贡献的研究者与高级工程师（需阅读 [CONTRIBUTING.md](https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md) 与 rustc-dev-guide）。

## 如何使用

### 前置条件

- 操作系统：macOS、Windows、Linux 及主流 Unix 变体（完整列表见 [rustup 文档](https://rustup.rs/)）。
- 日常开发推荐 **Stable** 通道；Nightly 仅用于尝鲜语言特性或编译器贡献。
- 从源码构建 rustc 需大量磁盘空间、C/C++ 编译工具链与数小时编译时间，复杂度远高于 rustup 安装（见 [INSTALL.md](https://github.com/rust-lang/rust/blob/master/INSTALL.md)）。

### 安装方式

**方式一：rustup（推荐大多数用户）**

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

按提示选择默认安装（Stable）。Windows 亦可从 [rustup.rs](https://rustup.rs/) 下载 `rustup-init.exe`。

**方式二：包管理器（部分平台）**

```bash
# Homebrew（macOS / Linux）
brew install rust
```

```bash
# Windows（winget）
winget install Rustlang.Rustup
```

更多平台安装选项见 [The Book — Installation](https://doc.rust-lang.org/book/ch01-01-installation.html)。

### 首次运行

```bash
rustc --version
cargo --version
```

创建并运行首个项目：

```bash
cargo new hello_rust --bin
cd hello_rust
cargo run
```

终端应输出 `Hello, world!`。

### 验证是否成功

- `rustc --version` 与 `cargo --version` 输出版本号，无 PATH 或权限错误。
- `cargo run` 在新建项目中成功编译并打印 `Hello, world!`。
- 运行 `rustup show` 确认 active toolchain 为 `stable`（或你预期的通道）。
- 查阅 [doc.rust-lang.org](https://doc.rust-lang.org/) 确认本地文档版本与工具链一致（`rustup doc` 可打开本地 Book）。

### 常见坑 / 注意事项

- **Stable vs Nightly**：生产与团队协作应锁定 Stable；依赖 Nightly 特性的 crate 会导致工具链不一致，CI 需显式 `rustup override`。
- **源码仓库 vs 日常使用**：clone 本 repo 不等于「安装 Rust」；贡献编译器需遵循 [INSTALL.md](https://github.com/rust-lang/rust/blob/master/INSTALL.md)，流程复杂且耗资源。
- **编译时间与 CI**：首次 `cargo build` 与依赖较多时编译较慢，建议启用 [sccache](https://github.com/mozilla/sccache) 或 CI 缓存 `~/.cargo/registry` 与 `target/`。
- **所有权学习曲线**：借用检查报错是常态，善用编译器提示与 [Rust By Example](https://doc.rust-lang.org/rust-by-example/)；避免过早使用 `unsafe` 绕过检查。
- **中国大陆网络**：crates.io 下载缓慢可配置 [镜像源](https://rustwiki.org/zh-CN/development-guide/starting/Developing.html#china-cratesio-index)（如 rsproxy、ustc）；rustup 组件更新亦可切换镜像。
- **许可证**：Rust 以 MIT / Apache-2.0 双许可分发（见仓库 LICENSE 文件）；商标使用须遵循 [Rust Foundation 商标政策](https://rustfoundation.org/policy/rust-trademark-policy/)。

---

# three.js

> 浏览器端 JavaScript 3D 库，支持 WebGL/WebGPU，轻量跨平台，适合 Web 可视化与交互场景。

- 页面：https://www.niceshare.site/github/threejs/
- 仓库：https://github.com/mrdoob/three.js
- 官网：https://threejs.org/
- 语言：JavaScript
- Stars：113261
- 许可证：MIT
- 标签：开发工具、前端、可视化
- 收录：2026-06-24（更新于 2026-06-24）

## 项目介绍

three.js 是面向浏览器的 JavaScript 3D 库，由 mrdoob 发起并长期维护，目标是提供易用、轻量、跨浏览器、通用场景的 3D 渲染能力。当前构建默认包含 WebGL 与 WebGPU 渲染器，SVG、CSS3D 等渲染器以 addon 形式提供。官方站点 [threejs.org](https://threejs.org/) 汇集海量示例、文档与入门手册；日常开发通过 npm 安装 `three` 即可，无需 clone 完整源码仓库。

## 核心特性

- **场景图模型**：以 Scene、Camera、Mesh、Material、Light 等对象组合 3D 世界，概念直观、上手曲线平缓
- **多渲染后端**：内置 WebGLRenderer 与 WebGPURenderer；SVGRenderer、CSS3DRenderer 等可作为 addon 按需引入
- **丰富几何与材质**：BoxGeometry、BufferGeometry、PBR 材质、纹理与后期处理等覆盖常见可视化需求
- **动画与交互**：`setAnimationLoop`、轨道控制器（OrbitControls 等 addon）、射线拾取支撑交互式 3D 应用
- **完善学习资源**：官方 [Examples](https://threejs.org/examples/)、[Docs](https://threejs.org/docs/)、[Manual](https://threejs.org/manual/) 与活跃社区（Discord、Discourse）

## 对用户价值

在 Web 上实现 3D 若直接操作 WebGL/WebGPU 底层 API，样板代码多、调试成本高。three.js 把场景搭建、相机、光照、材质与渲染循环封装成统一抽象，让前端与创意开发者能快速产出产品级 3D 体验：数据可视化、产品展示、数字孪生、轻量游戏与创意编程等。生态成熟，与 React（[react-three-fiber](https://github.com/pmndrs/react-three-fiber)）、Vue 等框架均有成熟集成方案；MIT 许可便于商业项目采用。

## 与替代方案

- 相比 [Babylon.js](https://www.babylonjs.com/)，three.js 更偏底层渲染库，API 粒度细、自由度大，需自行组合控制器与物理等能力；Babylon 内置编辑器、物理、粒子等一体化工具链，适合希望「开箱即用」的游戏向项目。
- 相比 [PlayCanvas](https://playcanvas.com/)，three.js 完全开源、可自托管，无厂商绑定；PlayCanvas 提供云端协作编辑器，更适合团队协作的游戏生产流程。
- 相比原生 WebGL/WebGPU，three.js 显著降低入门门槛，但抽象层带来一定性能与包体积开销；极致性能或定制管线场景可评估直接调用 GPU API 或更轻量的引擎。
- 边界说明：本仓库为 **three.js 源码**；应用开发通常 `npm install three` 并参阅 threejs.org，完整 clone 含历史约 2 GB，仅需源码贡献时使用 `--depth=1` 浅克隆。

## 适应人群

- 需要在网页中嵌入 3D 场景、模型展示或数据可视化的前端工程师与创意开发者。
- 评估 Web 3D 技术栈（与 Babylon.js、原生 WebGL 对比）的技术负责人与架构师。
- 使用 React/Vue 等框架构建交互式 3D 应用，希望借助成熟库与社区示例加速迭代的团队。

## 如何使用

### 前置条件

- 现代浏览器（支持 WebGL；WebGPU 需浏览器开启相应能力）。
- Node.js 18+ 与 npm/pnpm/Yarn（用于打包与本地开发）。
- 基础 JavaScript 与 DOM 知识；3D 概念（场景、相机、网格）有助于理解 API。

### 安装方式

**方式一：npm 安装（推荐，日常开发）**

```bash
npm install three
```

**方式二：Vite 等现代打包工具**

创建项目后安装 `three`，在入口文件中 `import * as THREE from 'three'` 即可（需配置 bundler 处理 ES modules）。

**方式三：clone 源码仓库（贡献或研究源码）**

完整历史体积约 2 GB，浅克隆可显著减小下载量：

```bash
git clone --depth=1 https://github.com/mrdoob/three.js.git
```

### 首次运行

最小示例（来自官方 README）：创建场景、相机、立方体网格，用 WebGLRenderer 渲染并旋转动画。

```javascript
import * as THREE from 'three';

const width = window.innerWidth, height = window.innerHeight;

const camera = new THREE.PerspectiveCamera(70, width / height, 0.01, 10);
camera.position.z = 1;

const scene = new THREE.Scene();

const geometry = new THREE.BoxGeometry(0.2, 0.2, 0.2);
const material = new THREE.MeshNormalMaterial();

const mesh = new THREE.Mesh(geometry, material);
scene.add(mesh);

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(width, height);
renderer.setAnimationLoop(animate);
document.body.appendChild(renderer.domElement);

function animate(time) {
  mesh.rotation.x = time / 2000;
  mesh.rotation.y = time / 1000;
  renderer.render(scene, camera);
}
```

在线可运行版本见 [jsfiddle 示例](https://jsfiddle.net/w43x5Lgh/)。更多场景见 [threejs.org/examples](https://threejs.org/examples/)。

### 验证是否成功

- 浏览器页面应显示旋转的彩色立方体，控制台无 WebGL 相关报错。
- 调整 `mesh.rotation` 或相机 `position`，画面应随之变化。
- 若使用打包工具，确认 `npm run dev` / `npm run build` 无模块解析错误。

### 常见坑 / 注意事项

- **源码仓库 vs npm 包**：产品集成请安装 npm 上的 `three`；clone 本仓库主要用于贡献或阅读源码，勿与日常依赖混为一谈。
- **版本迁移**：大版本升级前阅读 [Migration Guide](https://github.com/mrdoob/three.js/wiki/Migration-Guide) 与 [Releases](https://github.com/mrdoob/three.js/releases)，关注 API 破坏性变更。
- **OrbitControls 等 addon**：控制器、加载器（GLTFLoader 等）位于 `examples/jsm/`，需按文档路径单独 import，非 `three` 主包默认导出。
- **性能与资源**：大模型、高分辨率纹理需关注 draw call、纹理压缩与 LOD；移动端注意内存与帧率，必要时启用 `renderer.setPixelRatio` 上限。
- **WebGPU**：仍为演进中的渲染路径，生产环境请确认目标浏览器支持情况，并准备 WebGL 回退方案。

---

# gstack

> YC CEO Garry Tan 的 Claude Code 技能集，23 个斜杠命令覆盖从产品规划到发布上线。

- 页面：https://www.niceshare.site/github/gstack/
- 仓库：https://github.com/garrytan/gstack
- 语言：TypeScript
- Stars：111392
- 许可证：MIT
- 标签：AI 编程、Agent、开发工具
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

gstack 是 Y Combinator CEO [Garry Tan](https://x.com/garrytan) 开源的 **AI 结对编程工厂**：一套面向 Claude Code 的 23 个斜杠命令（Slash Skills），把单人会话拆成 CEO、设计师、工程经理、Staff 审查、QA、安全官、发布工程师等角色，按「思考 → 规划 → 构建 → 审查 → 测试 → 发布 → 复盘」的冲刺节奏串联。所有技能以 Markdown 定义、MIT 许可，支持 Claude Code 原生安装，也可通过 `./setup --host` 适配 Cursor、Codex、OpenCode 等十余种 Agent 宿主。

## 核心特性

- **产品澄清**：`/office-hours` 用六个强制问题重述需求，产出设计文档并喂给下游技能
- **多角色规划**：`/plan-ceo-review`、`/plan-eng-review`、`/plan-design-review`、`/plan-devex-review` 分别从战略、架构、视觉与开发者体验角度挑战方案
- **设计与原型**：`/design-consultation`、`/design-shotgun`、`/design-html` 覆盖设计系统、多方案探索与可上线 HTML 输出
- **质量与安全**：`/review` 自动修复明显问题；`/investigate` 强制根因排查；`/cso` 做 OWASP + STRIDE 审计；`/qa` 在真实浏览器中回归并补测试
- **发布闭环**：`/ship` 跑测试并开 PR；`/land-and-deploy`、`/canary`、`/benchmark` 覆盖合并、生产验证与性能基线
- **多宿主支持**：`./setup` 自动检测已安装 Agent，或通过 `--host cursor|codex|opencode|factory` 等定向安装
- **团队模式**：`gstack-team-init` 让共享仓库的队友自动获得一致技能版本，每小时静默检查更新

## 对用户价值

很多人用 Claude Code 时仍停留在「空白提示词 + 直接写代码」，缺少产品推敲、架构锁定、设计把关与发布纪律。gstack 把 Garry Tan 日常 ship 产品的流程固化成可复用命令：从 `/office-hours` 纠正「你要做的其实不是这个功能」开始，到 `/review` 与 `/qa` 在 CI 之外抓生产级 bug，再到 `/ship` 统一测试与 PR。对个人 builder，它提供接近小团队的节奏；对技术创始人，它把 CEO 视角的产品挑战编码进工作流，减少 AI 产出「能跑但不对」的 slop。

## 与替代方案

- 相比 [Superpowers](https://github.com/obra/superpowers) 等**方法论型技能库**，gstack 更偏 **Garry Tan 个人工程工厂**：角色划分更细（含 CEO 审阅、设计 shotgun、CSO 安全、SRE canary），且内置浏览器 QA 与发布流水线命令。
- 相比通用 Cursor Rules 或零散 prompt，gstack 提供**可安装的斜杠命令与团队同步机制**（`gstack-team-init`），技能之间有明确上下游（设计 doc → 规划 → 审查 → QA → ship）。
- 相比 Cline、Aider 等**以编辑/终端为中心**的 Agent 客户端，gstack 是**技能包而非 IDE**；若你需要深度 IDE 集成或本地模型路由，应继续用宿主工具，把 gstack 作为流程层叠加上去。
- 与 OpenClaw 等**多会话编排**可组合：OpenClaw 通过 ACP 拉起已装 gstack 的 Claude Code 会话；ClawHub 另有 4 个原生 OpenClaw 方法论技能（office-hours、ceo-review 等）。

## 适应人群

- 仍在亲自写代码的技术创始人、CEO，希望用结构化角色替代「想到哪写到哪」的 Claude Code 会话。
- 第一次使用 Claude Code，想要开箱即用的 `/office-hours` → `/review` → `/qa` 入门路径的开发者。
- Tech Lead / Staff 工程师，需要在每个 PR 上强制执行架构审查、浏览器 QA、安全审计与发布检查的团队。

## 如何使用

### 前置条件

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)（主路径）；多宿主用户需已安装目标 Agent（Cursor、Codex CLI 等）。
- [Git](https://git-scm.com/)、[Bun](https://bun.sh/) v1.0+；Windows 另需 [Node.js](https://nodejs.org/)。
- 对目标项目有 Git 读写权限；`/qa`、`/browse` 等技能需要可访问的 staging URL 或浏览器环境。

### 安装方式

**Claude Code（个人，约 30 秒）**

在 Claude Code 中粘贴以下指令，由 Claude 执行克隆与 `./setup`：

```text
Install gstack: run git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup then add a "gstack" section to CLAUDE.md that lists available skills: /office-hours, /plan-ceo-review, /review, /qa, /ship, /autoplan, /cso, and others from the gstack README.
```

或手动执行：

```bash
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup
```

**团队模式（推荐共享仓库）**

```bash
(cd ~/.claude/skills/gstack && ./setup --team) && ~/.claude/skills/gstack/bin/gstack-team-init required && git add .claude/ CLAUDE.md && git commit -m "require gstack for AI-assisted work"
```

将 `required` 改为 `optional` 可改为软性提示而非强制。

**Cursor / Codex / 其他宿主**

```bash
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack
cd ~/gstack && ./setup --host cursor   # 或 codex、opencode、factory 等
```

### 首次运行

1. 在 Claude Code 中运行 `/office-hours`，描述你正在构建的产品或功能。
2. 对想法运行 `/plan-ceo-review`，在已有分支上运行 `/review`。
3. 若有 staging 环境，对 URL 运行 `/qa https://your-staging-url`。
4. 完成上述四步即可判断 gstack 是否适合你的工作流；完整冲刺可继续 `/autoplan` → 实现 → `/ship`。

### 验证是否成功

- `~/.claude/skills/gstack`（或对应宿主技能目录）存在且 `./setup` 无报错。
- 输入 `/office-hours` 等命令时 Claude 按技能文档提问并产出设计文档，而非忽略斜杠命令。
- 团队模式下，队友克隆仓库后新 Claude Code 会话会自动拉取 gstack 更新（每小时节流检查）。

### 常见坑 / 注意事项

- gstack 技能链偏**完整产品冲刺**；修 README 错别字等小事不必强行走全套流程。
- `/browse` 与 Chrome MCP 有互斥约定：README 建议在 CLAUDE.md 中声明优先使用 gstack 的 `/browse`，避免与 `mcp__claude-in-chrome__*` 冲突。
- 多宿主需分别 `./setup --host <name>`；技能安装路径因 Agent 而异，见 README 宿主表。
- 仓库 star 增长极快，安装命令与技能列表以 [官方 README](https://github.com/garrytan/gstack) 为准；升级可用 `/gstack-upgrade` 或重新 clone。
- OpenClaw 用户见 [docs/OPENCLAW.md](https://github.com/garrytan/gstack/blob/main/docs/OPENCLAW.md)；ClawHub 有四项独立方法论技能可单独安装。

---

# Axios

> 基于 Promise 的跨端 HTTP 客户端，统一浏览器与 Node.js 的请求写法，拦截器与 JSON 处理开箱即用。

- 页面：https://www.niceshare.site/github/axios/
- 仓库：https://github.com/axios/axios
- 官网：https://axios-http.com
- 语言：JavaScript
- Stars：109084
- 许可证：MIT
- 标签：开发工具、前端、后端
- 收录：2026-06-24（更新于 2026-06-24）

## 项目介绍

Axios 是 JavaScript 生态中最广泛使用的 HTTP 客户端之一，以 Promise API 统一浏览器（XMLHttpRequest）与 Node.js（`http`/`https`）的请求体验。它提供请求/响应拦截器、自动 JSON 序列化与解析、超时与取消机制，以及表单与 multipart 上传等常见能力；官方文档站 [axios-http.com](https://axios-http.com) 覆盖 v1.x 完整 API。项目 MIT 许可，被 React、Vue、Next.js 等无数应用与 SDK 间接依赖，是前后端「发 HTTP 请求」的事实标准库之一。

## 核心特性

- **跨端一致 API**：同一套 `axios.get` / `post` / `request` 写法可在浏览器与 Node.js 中复用，降低全栈代码分裂
- **拦截器链**：在请求发出前注入 Token、统一 baseURL，在响应后集中处理错误码与数据转换
- **自动 JSON 与表单**：请求体自动序列化、响应自动解析 JSON；支持 `application/x-www-form-urlencoded` 与 `multipart/form-data`
- **超时、取消与错误分类**：`timeout` 配置避免请求无限挂起；`AbortController` / Cancel Token 取消在途请求；`AxiosError` 区分网络、超时与 HTTP 状态错误
- **扩展适配器**：除默认 XHR/Node 适配器外，提供 Fetch adapter、HTTP/2 等进阶选项（见官方文档）

## 对用户价值

若你在前端调用 REST API、在 Node 服务中访问第三方接口，或需要为多个微服务客户端统一鉴权与错误处理，Axios 能以极少样板代码覆盖 90% 场景。拦截器让你把 Token 刷新、日志、重试逻辑集中在一处，而不是在每个 `fetch` 调用里重复。相比裸 `fetch`，Axios 默认处理 JSON、查询参数（`params`）与常见 Content-Type，减少「忘记 `response.json()`」类低级错误。代价是包体积大于原生 `fetch`，且对 Stream、低层 HTTP 细节的控制不如 `node:http` 直接调用灵活。

## 与替代方案

- 相比原生 **fetch**，Axios 提供拦截器、超时、自动 JSON、更广的浏览器兼容策略（IE 需额外 polyfill）；fetch 零依赖、符合 Web 标准，适合现代浏览器/边缘运行时且追求最小 bundle 的场景。
- 相比 **jQuery.ajax**，Axios 不绑定 DOM、API 更现代（Promise/async-await），体积更小；遗留 jQuery 项目迁移时可逐步替换 ajax 调用。
- 相比 **got**（Node 专用），Axios 跨端统一；got 在 Node 侧流式下载、重试与 HTTP/2 等能力更专精，纯服务端高吞吐抓取可能更合适。
- 相比 **ky**（基于 fetch 的轻量封装），Axios 生态与 Stack Overflow 覆盖更广、拦截器模式更成熟；ky 更贴近 fetch 语义、包更轻，适合仅需薄封装的现代项目。
- 边界说明：Axios 是 HTTP 客户端而非 API 网关、ORM 或 RPC 框架；GraphQL、gRPC 或 WebSocket 实时通道需选用对应专用库。

## 适应人群

- 在 React、Vue、Svelte 等前端项目中调用后端 API、上传文件或处理鉴权刷新的前端与全栈工程师。
- 用 Node.js 编写脚本、BFF 或微服务、需要稳定出网 HTTP 调用的后端开发者。
- 维护内部 SDK 或 CLI 工具、希望统一请求配置、错误格式与重试策略的平台/基础设施团队。

## 如何使用

### 前置条件

- **浏览器**：主流现代浏览器（Chrome、Firefox、Safari、Edge 最新版）；IE 不支持 async/await，需额外 polyfill 并谨慎评估。
- **Node.js**：建议使用当前 LTS；包管理器任选 npm、yarn、pnpm 或 bun。
- 生产环境应为请求配置 **`timeout`**，避免 stalled 连接无限挂起（见[官方文档](https://axios-http.com/docs/intro)）。

### 安装方式

**方式一：包管理器（推荐）**

```bash
npm install axios
```

```bash
pnpm add axios
```

```bash
yarn add axios
```

```bash
bun add axios
```

**方式二：CDN（浏览器脚本，生产请锁定版本号）**

```html
<script src="https://cdn.jsdelivr.net/npm/axios@1/dist/axios.min.js"></script>
```

**导入方式（ESM / CommonJS）**

```js
import axios from "axios";
// const axios = require("axios");
```

### 首次运行

```js
import axios from "axios";

const response = await axios.get(
  "https://jsonplaceholder.typicode.com/posts/1",
  { timeout: 5000 }
);

console.log(response.data);
```

带查询参数与 POST 示例：

```js
await axios.get("/user", { params: { ID: 12345 } });

await axios.post("/user", {
  firstName: "Fred",
  lastName: "Flintstone",
});
```

### 验证是否成功

- `response.status` 为 2xx，`response.data` 包含预期 JSON 结构。
- 故意访问不存在路径时，`catch` 中应得到 `AxiosError`，且 `error.response?.status` 反映 HTTP 状态码。
- Node 与浏览器环境下同一套代码均可完成上述 GET 请求（注意 CORS：浏览器直连第三方 API 需服务端允许跨域）。

### 常见坑 / 注意事项

- **未设置 timeout**：无超时配置的请求可能在网络异常时永久 pending；生产务必传入 `timeout` 并处理 `ECONNABORTED` / `ETIMEDOUT`。
- **错误处理**：Axios 仅在 2xx 时 resolve；4xx/5xx 进入 `catch`，需通过 `error.response` 读取响应体，勿假设 `catch` 一定是网络故障。
- **CORS 与浏览器**：浏览器端请求跨域资源受同源策略限制；开发环境可配代理，生产需后端设置 CORS 或经 BFF 转发。
- **默认导出与 named export**：`require("axios")` 仅默认导出可用；部分打包器需 `import { default as axios } from "axios"`。
- **大版本升级**：v1.x 与 v0.x API 有差异，升级前阅读 [CHANGELOG](https://github.com/axios/axios/blob/master/CHANGELOG.md) 与[迁移说明](https://axios-http.com/docs/migration_guide)。

---

# Deno

> 基于 V8 与 Rust 的现代 JavaScript/TypeScript 运行时，默认权限沙箱，原生支持 TS 与 Web 标准 API。

- 页面：https://www.niceshare.site/github/deno/
- 仓库：https://github.com/denoland/deno
- 官网：https://deno.com
- 语言：Rust
- Stars：107163
- 许可证：MIT
- 标签：开发工具、CLI、后端
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Deno 是由 [Deno Land Inc.](https://deno.com/) 维护的现代 JavaScript、TypeScript 与 WebAssembly 运行时，基于 V8、Rust 与 Tokio 构建。它强调**安全默认值**（显式权限模型）与**开发者体验**（原生 TypeScript、Web 标准 API、单二进制分发），并提供 [Deno Deploy](https://deno.com/deploy) 边缘托管与 [JSR](https://jsr.io/) 包注册表，形成从本地开发到部署的完整链路。

## 核心特性

- **权限沙箱**：文件、网络、环境变量、子进程等能力需 `--allow-*` 显式授权，降低脚本误执行风险
- **原生 TypeScript**：`.ts` / `.tsx` 可直接 `deno run`，无需单独 tsconfig 或转译步骤（仍可配置）
- **Web 标准 API**：`fetch`、`Request`/`Response`、`Deno.serve` 等与浏览器对齐，降低前后端心智切换
- **内置工具链**：`deno fmt`、`deno lint`、`deno test`、`deno compile` 覆盖格式化、静态检查、测试与单文件编译
- **JSR 与标准库**：官方 [Standard Library](https://jsr.io/@std) 与 JSR 注册表面向现代 ESM/TypeScript 包发布与消费

## 对用户价值

若你希望在新项目中减少「Node + npm + ESLint + Jest + ts-node」的拼装成本，Deno 用单个 `deno` 二进制覆盖运行、测试与常用开发命令，并对 TypeScript 开箱即用。权限模型让 CLI 脚本与第三方依赖的副作用更可审计，适合对安全边界敏感的场景。对已有 npm 生态项目，Deno 持续增强 Node/npm 兼容（`deno install npm:...`），可渐进评估迁移；代价是部分 Node 原生模块、历史 CommonJS 包与企业级 LTS 节奏仍不如 Node.js 成熟，生产落地需对照官方兼容文档验证。

## 与替代方案

- 相比 [Node.js](https://nodejs.org/)，Deno 默认权限沙箱、原生 TypeScript 与 Web API 取向更明显；Node.js npm 生态规模、第三方包验证广度、LTS 发布节奏与企业支持经过更长生产检验，存量项目更常选 Node。
- 相比 [Bun](https://bun.sh/)，Deno 更强调安全默认值与 Web 标准；Bun 更聚焦 npm 兼容与一体化 dev 速度（安装、测试、打包），适合在 Node 生态内追求极致启动与工具链收敛的团队。
- 相比单独使用 [TypeScript](https://www.typescriptlang.org/) + [Vitest](https://vitest.dev/) + [esbuild](https://esbuild.github.io/)，Deno 用运行时内置工具减少配置面；若团队已深度定制各工具链或依赖特定 Node 原生扩展，拆分方案仍可能更灵活。
- 边界说明：Deno 不是容器编排或数据库产品；复杂 monorepo、特定 `node-gyp` 原生 addon 或冷门 Node API 需在目标环境实测，不宜假设 100% 兼容。

## 适应人群

- 新建 greenfield TypeScript 全栈或 CLI 项目，希望零配置运行 TS、并控制脚本权限边界的个人开发者与小团队。
- 关注 Web 标准 API、边缘部署（Deno Deploy）与 JSR 包发布的现代 JavaScript 工程师。
- 在 Node 与 Deno 之间做运行时选型、或评估 Deno 作为脚本/工具链加速器的后端与 DevOps 负责人。

## 如何使用

### 前置条件

- 支持平台：macOS、Linux、Windows（x64 / arm64），详见 [安装文档](https://docs.deno.com/runtime/manual/getting_started/installation)。
- 无需预装 Node.js 或 npm；从源码构建需 Rust 工具链，复杂度远高于安装官方二进制。
- 运行需网络权限的示例（如 HTTP 服务）时，需显式传入 `--allow-net` 等权限标志。

### 安装方式

**方式一：官方安装脚本（推荐）**

```bash
# macOS / Linux
curl -fsSL https://deno.land/install.sh | sh
```

```powershell
# Windows PowerShell
irm https://deno.land/install.ps1 | iex
```

**其他方式**

```bash
# Homebrew（macOS）
brew install deno

# npm（全局）
npm install -g deno
```

```powershell
# Chocolatey / WinGet / Scoop（Windows）
choco install deno
winget install --id=DenoLand.Deno
scoop install main/deno
```

升级至最新稳定版：

```bash
deno upgrade
```

### 首次运行

创建 `server.ts`：

```typescript
Deno.serve((_req: Request) => {
  return new Response("Hello, world!");
});
```

启动本地 HTTP 服务（需网络权限）：

```bash
deno run --allow-net server.ts
```

浏览器访问 `http://localhost:8000` 应看到 `Hello, world!`。

### 验证是否成功

```bash
deno --version          # 应输出版本号
deno run --allow-net server.ts   # 本地 8000 端口可响应
deno test               # 若有 *_test.ts，应执行测试套件
```

确认 `~/.deno/bin`（或安装脚本提示的路径）已加入 `PATH`，新开终端后 `which deno` 可找到可执行文件。

### 常见坑 / 注意事项

- **权限模型**：未加 `--allow-read` / `--allow-net` 等标志时，文件与网络访问会被拒绝；生产脚本应最小化授权范围，勿习惯性 `--allow-all`。
- **Node/npm 兼容非 100%**：部分 CommonJS 包、原生 addon 或 Node 专有 API 可能无法直接运行，迁移前查阅 [Node 兼容文档](https://docs.deno.com/runtime/manual/node/) 并在 staging 验证。
- **模块解析差异**：Deno 默认 ESM 与 URL/import map 取向，与 Node 的 `node_modules` 解析习惯不同；消费 npm 包时优先使用 `npm:` 说明符或 `deno.json` 配置。
- **从源码构建**：clone 本 repo 用于贡献或定制构建，日常开发安装官方二进制即可，无需自行编译 Rust 工程。

---

# Immich

> 高性能自托管照片与视频库，Google Photos 开源替代，支持手机自动备份与人脸检索。

- 页面：https://www.niceshare.site/github/immich/
- 仓库：https://github.com/immich-app/immich
- 官网：https://immich.app
- 语言：TypeScript
- Stars：105461
- 许可证：AGPL-3.0
- 标签：本地模型、自托管、自动化
- 收录：2026-06-20（更新于 2026-07-04）

## 项目介绍

Immich 是面向个人与家庭的高性能自托管照片与视频管理方案，常被视作 Google Photos 的开源替代。它提供 Web 界面与 iOS/Android 客户端，支持后台自动备份、相册共享与人脸聚类，让珍贵影像留在自有服务器而非公有云。

## 核心特性

- 移动端打开即自动备份，支持选择性相册、去重与 Live Photo / Motion Photo
- Web 与 App 均可浏览、下载照片与视频，支持 RAW 与 360° 影像
- 人脸聚类、CLIP 语义搜索、EXIF 与地图视图，便于按人物、地点或内容检索
- 多用户、共享相册、伴侣共享、公开链接与 OAuth 登录
- 虚拟滚动与离线浏览（移动端），大库浏览体验接近商业相册产品
- 官方 Docker Compose 部署模板，文档与 Demo 站点完善

## 对用户价值

手机相册越拍越多，云厂商容量与隐私条款却不可控。Immich 把「备份 → 整理 → 检索 → 共享」放在自管服务器上，原始文件与元数据归你所有；配合 3-2-1 备份策略，比单纯依赖单一云相册更可持续。

## 与替代方案

- 相比 Google Photos / iCloud，Immich 数据留在私有基础设施，无订阅容量限制，但需自行维护服务器、HTTPS 与备份。
- 相比 PhotoPrism，Immich 更强调移动端自动备份与现代相册交互（Memories、伴侣共享等），社区增长更快；PhotoPrism 在索引与权限模型上更偏「图库服务器」路线。
- 相比 Nextcloud Photos，Immich 专注影像场景，人脸与 CLIP 搜索、移动备份体验更完整；若已深度使用 Nextcloud 生态，集成相册可能更省事。
- 项目采用 AGPL-3.0；商业托管或二次分发需留意许可义务。官方强调遵循 3-2-1 备份，勿把 Immich 当作唯一副本。

## 适应人群

- 想从 Google Photos 迁移、又希望保留自动备份与「几年前今天」回忆功能的家庭用户。
- 已有 NAS / Homelab，愿意用 Docker 跑一套私有影像库的 self-host 爱好者。
- 摄影爱好者需要 RAW 支持、地图与人脸整理，又不想把原片长期托管在公有云的人。

## 如何使用

### 前置条件

- 推荐 Linux 64 位主机，已安装 Docker Engine 与 **Docker Compose 插件**（命令为 `docker compose`，非旧版 `docker-compose`）。
- 硬件建议：至少 6GB RAM（8GB 更稳）、4 核 CPU；`UPLOAD_LOCATION` 与 Postgres 数据目录需足够磁盘，缩略图与转码通常额外占库容 10–20%。
- Postgres 数据建议放本地 SSD，避免网络盘；Windows/macOS 可用 Docker Desktop，但官方更推荐 Linux 生产部署。

### 安装方式

官方推荐 Docker Compose。创建目录并下载最新 Compose 与环境文件：

```bash
mkdir ./immich-app && cd ./immich-app
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env
```

编辑 `.env`：设置 `UPLOAD_LOCATION`（照片存储路径）、`DB_PASSWORD`（建议 `A-Za-z0-9`）、时区 `TZ` 等，然后启动：

```bash
docker compose up -d
```

完整说明见 [官方安装文档](https://docs.immich.app/install/docker-compose)。

### 首次运行

容器启动后，浏览器访问 `http://<服务器IP>:2283`（默认端口以 `.env` 为准），创建管理员账户。在 App Store / Google Play 安装 Immich 客户端，将「服务器地址」指向你的实例，登录后开启自动备份并选择相册范围。

### 验证是否成功

- Web UI 可登录，上传测试照片后能在时间线中看到缩略图。
- 移动端备份任务正常，重复文件不会被二次入库。
- 人脸/搜索索引需一定时间；可在管理界面查看机器学习任务是否完成。

### 常见坑 / 注意事项

- Ubuntu 自带 `docker.io` 可能导致 `docker compose` 异常，应改用 [Docker 官方仓库](https://docs.docker.com/engine/install/) 安装 Engine。
- 数据库 healthcheck 若报 `start_interval` 需 Docker Engine v25+，可暂时注释 `docker-compose.yml` 中 database 段对应行。
- 仅 4GB 内存时可禁用机器学习功能，但人脸与 CLIP 搜索将不可用。
- **务必实施 3-2-1 备份**（官方 README 强调）；升级前阅读 [Post Installation](https://docs.immich.app/install/post-install) 与 [Upgrading](https://docs.immich.app/install/upgrading) 指南。

---

# CC Switch

> 跨平台桌面工具，一键切换 Claude Code、Codex、Gemini CLI 等七种 AI 编程客户端的供应商与 MCP 配置。

- 页面：https://www.niceshare.site/github/cc-switch/
- 仓库：https://github.com/farion1231/cc-switch
- 官网：https://ccswitch.io
- 语言：Rust
- Stars：104626
- 许可证：MIT
- 标签：开发工具、AI 编程、CLI
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

[CC Switch](https://ccswitch.io) 是一款基于 Tauri 2 的跨平台桌面应用，把 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw 与 Hermes 七种 AI 编程工具的供应商配置收进同一界面。你不必再分别编辑 JSON、TOML 或 `.env`，也不必为切换 API 中继或官方账号而手动改多处文件；托盘菜单可秒切供应商，SQLite 原子写入与自动备份降低配置损坏风险。项目 MIT 开源，macOS 版本已通过 Apple 公证。

## 核心特性

- **七种工具、五十余预设**：覆盖 Claude Code / Desktop、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes；含 AWS Bedrock、NVIDIA NIM 与社区中继，一键导入 API Key
- **通用供应商**：一份配置可同时同步到 Claude Code、Codex 与 Gemini CLI
- **统一 MCP、Prompts 与 Skills**：单面板管理多应用的 MCP 服务器、CLAUDE.md / AGENTS.md / GEMINI.md 提示词，以及从 GitHub 或 ZIP 一键安装的技能包
- **本地代理与故障转移**：格式转换、熔断、健康检查与按应用/供应商粒度的代理接管
- **托盘快切与云同步**：系统托盘即时切换；支持 Dropbox、OneDrive、iCloud、WebDAV 跨设备同步供应商数据
- **用量与成本看板**：按模型自定义单价，追踪请求、Token 与花费趋势
- **会话与工作区**：浏览、搜索并恢复多源对话历史；OpenClaw 场景下可编辑 AGENTS.md、SOUL.md 等代理文件

## 对用户价值

现代 AI 编程往往同时使用多款 CLI，但每套工具的配置格式、MCP 目录与 Skills 路径互不兼容，换供应商意味着重复劳动，还容易漏改某处导致「明明切了 Key 却仍走旧路由」。CC Switch 把「加供应商 → 启用 → 托盘切换 → MCP/Skills 同步」收成可视化流程：首次启动可导入现有 CLI 配置为默认供应商，切换后除 Claude Code 支持热切换外，其余工具重启终端即可生效。对个人开发者，它降低多账号、多中继试错成本；对重度用户，统一 MCP 与 Skills 面板避免在七个工具间各维护一套清单。

## 与替代方案

- 相比**手写配置文件**（直接改 `~/.claude/settings.json`、Codex TOML、Gemini `.env` 等），CC Switch 提供预设库、导入导出、共享配置片段与备份，并减少误删导致 CLI 不可用的风险（始终保留至少一个活跃供应商）。
- 相比 **Continue、Cline** 等**内置模型路由的 IDE/终端 Agent**，CC Switch 是**配置管理层**而非编码助手本身；适合已选定 Claude Code / Codex 等宿主，只想集中管 Key、端点与中继的场景。
- 相比各 CLI **自带的官方登录 OAuth**，CC Switch 便于在「官方预设」与「第三方中继预设」之间来回切换，Codex 还支持多个 Plus/Team 官方账号切换；但若你只需单一官方订阅且从不换供应商，直接官方登录更轻量。
- 与 **OpenClaw、Superpowers** 等可组合：CC Switch 管供应商与 MCP/Skills 同步，编排与工作流仍由各自工具承担。

## 适应人群

- 同时在 Claude Code、Codex、Gemini CLI 等多款 AI 编程 CLI 间切换的个人开发者。
- 使用 API 中继、Bedrock、NIM 或自建网关，需要快速 A/B 供应商与监控用量的效率型用户。
- 希望用统一面板管理 MCP 服务器、Prompts 与 Skills，并跨设备同步配置的重度 AI 编程用户。

## 如何使用

### 前置条件

- **Windows**：Windows 10 及以上
- **macOS**：macOS 12 (Monterey) 及以上
- **Linux**：Ubuntu 22.04+ / Debian 11+ / Fedora 34+ 等主流发行版
- 已安装至少一种受支持工具（如 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、Codex CLI、Gemini CLI 等）；切换供应商后除 Claude Code 外通常需**重启终端或对应 CLI**

### 安装方式

**macOS（推荐 Homebrew）**

```bash
brew install --cask cc-switch
```

更新：

```bash
brew upgrade --cask cc-switch
```

**macOS 手动安装**：从 [Releases](https://github.com/farion1231/cc-switch/releases) 下载 `.dmg`（推荐）或 `.zip`。

**Windows**：从 Releases 下载 `CC-Switch-v{version}-Windows.msi` 安装包，或 `Windows-Portable.zip` 便携版。

**Linux**：从 Releases 选择 `.deb`（Debian/Ubuntu）、`.rpm`（Fedora/RHEL）或 `.AppImage`（通用）。

**Arch Linux**：

```bash
paru -S cc-switch-bin
```

### 首次运行

1. 启动 CC Switch；首次打开可**导入现有 CLI 配置**作为默认供应商。
2. 点击「添加供应商」→ 选择预设或自定义 API Key / 端点 → 保存。
3. 在主界面选中供应商并点击「启用」，或从**系统托盘**直接点击供应商名称完成快切。
4. 重启终端或对应 CLI 使配置生效（Claude Code 可热切换，无需重启）。
5. 可选：在「MCP」「Prompts」「Skills」面板添加服务器、提示词预设或从 GitHub 安装技能包。

### 验证是否成功

- 托盘或主界面显示当前启用的供应商名称。
- 打开对应 CLI（如 `claude`），确认请求走预期模型或端点。
- 检查数据目录 `~/.cc-switch/cc-switch.db` 与 `~/.cc-switch/backups/` 是否已创建（表示数据库与自动备份正常）。
- 在用量看板中发起一次请求，确认统计有记录（若已配置定价）。

### 常见坑 / 注意事项

- **切换后未生效**：多数工具需重启终端；仅 Claude Code 支持供应商热切换。
- **插件配置丢失**：使用「编辑供应商 → 共享配置面板 → 从当前供应商提取」保存通用片段；新建供应商时默认勾选「写入共享配置」。
- **无法删除当前活跃供应商**：设计为至少保留一份配置，避免对应 CLI 完全不可用；不常用的工具可在设置中隐藏。
- **回到官方登录**：从预设添加「官方登录」供应商并切换，再执行对应 CLI 的 Log out / Log in 或 OAuth 流程。
- **数据位置**：数据库 `~/.cc-switch/cc-switch.db`，本地设置 `settings.json`，Skills 默认符号链接到各应用目录；升级前可查看 [CHANGELOG](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md)。
- **Flatpak**：官方 Release 不含 Flatpak 包，需自行从 `.deb` 构建（见仓库 `flatpak/README.md`）。

---

# Windows Terminal

> Windows 现代命令行终端：多标签、丰富渲染与主题配置，并与系统控制台同源演进。

- 页面：https://www.niceshare.site/github/terminal/
- 仓库：https://github.com/microsoft/terminal
- 官网：https://aka.ms/terminal
- 语言：C++
- Stars：104072
- 许可证：MIT
- 标签：CLI、开发工具、工作流
- 收录：2026-07-19（更新于 2026-07-19）

## 项目介绍

Windows Terminal 是微软开源的现代终端应用，面向 Windows 命令行用户提供多标签、富文本、全球化、主题与可配置体验。同一仓库还包含 Windows 控制台宿主 `conhost.exe` 以及双方共享的渲染、文本缓冲与 VT 解析组件，是 Windows 命令行基础设施的官方演进主线，而非第三方外壳包装。

## 核心特性

- **现代终端 UX**：标签页、分屏、丰富文本与全球化支持，面向日常命令行生产力
- **主题与可配置**：配色、字体（含 Cascadia Code 生态）、样式与配置文件，适配不同 Shell 与工作流
- **高性能目标**：在功能增强的同时控制内存与功耗，避免「好看但拖慢机器」
- **与控制台同源**：共享 DirectWrite 渲染、UTF-8/UTF-16 文本缓冲、VT 解析器等核心组件；`conhost` 继续承担兼容性职责
- **多发行通道**：Stable / Preview，以及追踪 `main` 的 Canary（App Installer 或便携 ZIP）

## 对用户价值

经典 Windows 控制台受兼容性约束，难以原生提供标签、完善 Unicode/Emoji 等社区长期诉求。Windows Terminal 把多会话管理、可读渲染与主题配置做成一等公民，让 PowerShell、CMD、WSL、SSH 等配置文件在同一窗口协作。对 Windows 开发者与运维来说，它通常是换机后最先装的官方终端，而不是再叠一层第三方模拟器。

## 与替代方案

- 相比 **旧版 `conhost` 控制台**，Terminal 提供标签、现代渲染与配置体验；`conhost` 仍负责兼容性与 Console API，二者互补而非简单替代。
- 相比 **Warp** 等 AI 原生终端，Windows Terminal 更偏官方、轻账户依赖与系统集成；Warp 在块编辑与 Agent 工作流上更激进，但产品形态与许可策略不同。
- 相比 **Alacritty / WezTerm / Kitty** 等跨平台 GPU 终端，Windows Terminal 深度绑定 Windows（含 Store 自动更新、系统控制台组件）；若团队要在 macOS/Linux 上统一同一套终端配置，跨平台方案更合适。
- 若主要在 **VS Code / Cursor 内置终端** 里干活，不必强行迁移；独立 Terminal 更适合同时管理多个 Shell/WSL/远程会话的桌面工作区。

## 适应人群

- 每天在 Windows 上切换 PowerShell、CMD、WSL 或 SSH 的后端、全栈与 DevOps 工程师。
- 希望用官方维护、可自动更新的现代终端替换旧控制台窗口的个人开发者。
- 关注 Windows 命令行基础设施、ConPTY/VT 兼容或希望贡献 C++ 终端内核的贡献者。

## 如何使用

### 前置条件

- **Windows 10 2004（build 19041）或更高版本**
- 普通使用：无需自行编译；从 Microsoft Store / winget / GitHub Releases 安装即可
- 从源码构建（可选）：需 Developer Mode、PowerShell 7+、Windows SDK、Visual Studio 等，见仓库 README「Developer Guidance」

### 安装方式

- **推荐：Microsoft Store**（自动更新）：

打开 [aka.ms/terminal](https://aka.ms/terminal) 从 Microsoft Store 安装。

- **winget**：

```powershell
winget install --id Microsoft.WindowsTerminal -e
```

> 安装较新稳定版时，建议 WinGet 客户端为 1.6.2631 或更高，以便正确处理依赖。

- **GitHub Releases（手动）**：

从 [Releases](https://github.com/microsoft/terminal/releases) 下载 `Microsoft.WindowsTerminal_<version>.msixbundle`，双击安装；或在 PowerShell 中执行：

```powershell
# PowerShell 7+ 可能需要先执行：
# Import-Module Appx -UseWindowsPowerShell
Add-AppxPackage Microsoft.WindowsTerminal_<versionNumber>.msixbundle
```

手动安装不会自动更新，需自行跟进新版本；旧版 Windows 10 若提示缺少框架包，可能需安装 VC++ v14 Desktop Framework Package。

- **非官方包管理器（社区维护）**：

```powershell
choco install microsoft-windows-terminal
# 或
scoop bucket add extras
scoop install windows-terminal
```

- **Canary（每日构建，稳定性最低）**：见 [aka.ms/terminal-canary-installer](https://aka.ms/terminal-canary-installer) 或便携 ZIP（[x64](https://aka.ms/terminal-canary-zip-x64) 等）。

### 首次运行

启动 Windows Terminal 后，在设置中为 PowerShell、CMD、WSL 等添加或调整配置文件，按需设置默认配置、字体与配色。文档入口：[aka.ms/terminal-docs](https://aka.ms/terminal-docs)。

### 验证是否成功

确认可新建标签/窗格、切换不同 Shell 配置文件，且文本、颜色与 Unicode 显示正常。若从 Store / winget 安装，应用应出现在开始菜单并可正常启动。

### 常见坑 / 注意事项

- **平台限定**：面向 Windows；macOS/Linux 请另选终端。
- **手动安装无自动更新**：GitHub / 部分第三方包方式需自己跟进 Releases。
- **Canary 不稳定**：追踪 `main`，适合尝鲜，不建议作为唯一生产终端。
- **源码调试易踩坑**：本地构建请部署 `CascadiaPackage`；直接跑 `WindowsTerminal.exe` / 误开 `OpenConsole` 可能看起来像旧控制台。
- **贡献前先读指南**：功能开发前请遵循仓库 [CONTRIBUTING.md](https://github.com/microsoft/terminal/blob/main/CONTRIBUTING.md)，避免重复劳动。

---

# Tailwind CSS

> 实用优先的 CSS 框架，用工具类快速搭建定制界面，零运行时，与 Vite 等现代构建链深度集成。

- 页面：https://www.niceshare.site/github/tailwindcss/
- 仓库：https://github.com/tailwindlabs/tailwindcss
- 官网：https://tailwindcss.com
- 语言：TypeScript
- Stars：95666
- 许可证：MIT
- 标签：开发工具、前端、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Tailwind CSS 是由 [Tailwind Labs](https://tailwindcss.com) 维护的实用优先（utility-first）CSS 框架：你在 HTML 或组件中直接使用语义化的工具类（如 `flex`、`pt-4`、`text-center`），框架扫描源码后生成对应的静态 CSS，而非预置固定组件样式。Tailwind CSS v4 采用零运行时设计，通过 `@tailwindcss/vite` 等插件与 Vite、PostCSS 及主流前端框架深度集成。本仓库为框架源码；完整文档与安装指南见 [tailwindcss.com](https://tailwindcss.com)。

## 核心特性

- **实用优先工具类**：以原子化 class 组合界面，减少手写 CSS 与命名负担，设计变更时直接在 markup 中调整
- **零运行时、构建时生成**：扫描 HTML/JS/模板中的 class 名，产出精简静态 CSS，不增加浏览器端 JS 开销
- **现代构建链集成**：官方提供 Vite 插件（`@tailwindcss/vite`）、PostCSS、CLI 及 Next.js、Nuxt、SvelteKit 等框架指南
- **可定制设计系统**：通过 CSS 变量与 `@theme` 配置色板、间距、断点等，兼顾一致性与项目级品牌扩展
- **活跃社区与文档**：含完整 [Installation](https://tailwindcss.com/docs/installation)、[Framework Guides](https://tailwindcss.com/docs/installation/framework-guides) 与 GitHub Discussions 讨论区

## 对用户价值

传统 CSS 常因全局命名冲突、样式层级膨胀与「改一处动全身」而拖慢迭代。Tailwind 把样式决策收敛到组件 markup 旁，配合 IDE 补全与官方文档，原型到生产的样式迭代更快；构建时 purge 未使用的 class，避免整库 CSS 打进 bundle。团队若已采用 React、Vue、Svelte 等组件化栈，Tailwind 与组件模型天然契合，设计 token 可通过配置统一，降低设计与工程协作成本。日常开发通过 npm 安装 `tailwindcss` 并参阅官方文档即可，无需 fork 本仓库。

## 与替代方案

- 相比 [Bootstrap](https://getbootstrap.com/)，Tailwind 不提供固定 UI 组件库，而是提供可组合的工具类，界面定制自由度更高；Bootstrap 适合快速套用成熟组件，Tailwind 适合需要独特视觉的产品。
- 相比 [Bulma](https://bulma.io/) 等语义化 CSS 框架，Tailwind 的 utility-first 写法初期类名较多，但减少在 HTML 与 CSS 文件间跳转；Bulma 的 class 语义更直观，学习曲线因团队背景而异。
- 相比手写 [Sass/Less](https://sass-lang.com/) 或 CSS Modules，Tailwind 内置 spacing、color、responsive 等设计约束，减少「魔法数字」；纯 CSS 方案在极端定制场景下有时更灵活，但需自行维护设计 token 与 purge 策略。
- 边界说明：本仓库是 **Tailwind CSS 核心源码**；应用集成请按 [官方安装文档](https://tailwindcss.com/docs/installation) 选择 Vite、PostCSS 或 CLI，勿将 clone 本 repo 等同于在项目中启用 Tailwind。

## 适应人群

- 需要快速搭建定制界面、并希望样式与组件 markup 共处的前端工程师。
- 评估原子化 CSS 或设计系统落地方式，需在 Bootstrap 与 utility-first 之间做技术选型的团队负责人。
- 使用 Vite、Next.js、Nuxt、SvelteKit 等现代栈，希望统一 spacing、配色与响应式断点工作流的全栈开发者。

## 如何使用

### 前置条件

- Node.js 18+（以 [tailwindcss.com 安装文档](https://tailwindcss.com/docs/installation) 与所选脚手架要求为准）。
- npm、pnpm 或 Yarn 等包管理器。
- 已有 Vite 项目，或计划通过 `npm create vite@latest` 创建新项目；其他构建方式见 [Framework Guides](https://tailwindcss.com/docs/installation/framework-guides)。

### 安装方式

**方式一：Vite 插件（官方推荐，Tailwind CSS v4）**

```bash
npm create vite@latest my-project
cd my-project
npm install tailwindcss @tailwindcss/vite
```

在 `vite.config.ts` 中注册插件：

```ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [tailwindcss()],
})
```

在 CSS 入口文件（如 `src/style.css`）添加：

```css
@import "tailwindcss";
```

**方式二：PostCSS 或 CLI**

见 [Using PostCSS](https://tailwindcss.com/docs/installation/using-postcss) 与 [Tailwind CLI](https://tailwindcss.com/docs/installation/tailwind-cli)。快速原型可试用 [Play CDN](https://tailwindcss.com/docs/installation/play-cdn)（仅适合开发演示，不推荐生产）。

### 首次运行

启动开发服务器：

```bash
npm run dev
```

在 HTML 或组件中使用工具类，例如：

```html
<h1 class="text-3xl font-bold underline">Hello world!</h1>
```

确保页面已引入编译后的 CSS（Vite 会通过 `import './style.css'` 或框架默认配置处理）。

### 验证是否成功

- 浏览器打开 dev server 地址，标题应呈现 `text-3xl`、`font-bold`、`underline` 等样式。
- 修改 class（如改为 `text-red-500`），保存后应热更新生效。
- 运行 `npm run build` 成功产出生产构建；检查产物 CSS 体积合理且未包含未使用的工具类冗余。

### 常见坑 / 注意事项

- **源码仓库 vs npm 包**：日常项目在依赖中安装 `tailwindcss`（及 `@tailwindcss/vite` 等）即可；clone 本仓库用于贡献或与 Tailwind 内部包开发，见 [Contributing](https://github.com/tailwindlabs/tailwindcss/blob/main/.github/CONTRIBUTING.md)。
- **v3 与 v4 差异**：v4 默认 `@import "tailwindcss"` 与 Vite 插件路径，迁移旧项目请对照 [Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide)。
- **class 扫描范围**：构建工具需能扫描到所有含 Tailwind class 的模板与组件路径；Monorepo 或动态 class 字符串可能导致样式缺失，需按文档配置 content/source。
- **Play CDN 限生产**：CDN 方式便于 CodePen 式试用，生产环境应使用构建时生成以控制体积与缓存策略。

---

# Puppeteer

> 通过 DevTools Protocol 控制 Chrome/Firefox 的 Node.js 浏览器自动化库，默认无头运行，常用于 E2E 测试与网页抓取。

- 页面：https://www.niceshare.site/github/puppeteer/
- 仓库：https://github.com/puppeteer/puppeteer
- 官网：https://pptr.dev
- 语言：TypeScript
- Stars：95119
- 许可证：Apache-2.0
- 标签：自动化、开发工具、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Puppeteer 是 Google Chrome 团队维护的 Node.js 库，通过 [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) 或 [WebDriver BiDi](https://pptr.dev/webdriver-bidi) 以高层 API 驱动 Chrome 或 Firefox。默认以无头（headless）模式运行，也支持有界面调试。仓库为 monorepo，日常开发安装 npm 包 `puppeteer` 或 `puppeteer-core` 即可；官方文档与 API 参考见 [pptr.dev](https://pptr.dev/docs)。

## 核心特性

- **高层浏览器控制 API**：`launch`、`newPage`、`goto`、点击、键盘输入、截图、PDF 导出等常见自动化能力开箱即用
- **Chrome 与 Firefox 双引擎**：Chrome 通过 DevTools Protocol；Firefox 走 WebDriver BiDi，跨浏览器场景可统一脚本结构
- **`puppeteer` / `puppeteer-core` 双包策略**：完整包安装时下载匹配版本浏览器；core 包仅作库使用，需自行指定 `executablePath` 或配合 `@puppeteer/browsers` 管理二进制
- **Locator 与可访问性选择器**：支持 `::-p-aria()`、`::-p-text()` 等语义化定位，减少 brittle CSS 选择器依赖
- **浏览器下载与配置体系**：`npx puppeteer browsers install`、`.puppeteerrc.js` 与 `PUPPETEER_CACHE_DIR` 等机制便于 CI 与容器环境复现
- **生态延伸**：官方推荐 [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp) 作为基于 Puppeteer 的 MCP 服务器；并实验性支持 [WebMCP](https://pptr.dev/guides/webmcp)

## 对用户价值

若你需要在 Node.js 中程序化打开网页、填表、截图、生成 PDF、抓取动态渲染内容或跑端到端回归，Puppeteer 提供了比直接调 DevTools 更低门槛的抽象。安装 `puppeteer` 时会拉取兼容版 Chrome，本地与 CI 环境一致性较好；在 Docker 或受限网络下，可改用 `puppeteer-core` 挂载已有 Chromium，或通过配置缓存目录避免重复下载。对 AI Agent 与自动化平台，Puppeteer 也是 chrome-devtools-mcp 等「浏览器工具」的常见底层实现，适合把「让模型操作真实浏览器」接入工作流。

## 与替代方案

- 相比 [Playwright](https://github.com/microsoft/playwright)，Puppeteer 与 Chrome 生态绑定更深、历史更久，Stars 与 npm 下载量庞大；Playwright 内置多浏览器并行、自动等待与更强的一体式测试 Runner，新项目做跨浏览器 E2E 时 Playwright 往往更省心。
- 相比 [Selenium](https://www.selenium.dev/)，Selenium 基于 WebDriver 标准、多语言客户端成熟，适合已有 Java/Python 测试栈的企业；Puppeteer 专注 JavaScript/TypeScript，API 更现代，与 Node 脚本和前端仓库集成更自然。
- 相比 [Cypress](https://www.cypress.io/)，Cypress 强调「在浏览器内跑测试」的开发者体验与 Time Travel 调试，更偏前端团队交互式 E2E；Puppeteer 更通用，适合爬虫、批处理、PDF/截图流水线及底层自动化，而非开箱即用的测试 UI 框架。
- 边界说明：本仓库为 **Puppeteer 源码 monorepo**；应用侧通常 `npm i puppeteer` 即可，无需 clone 本仓库。`puppeteer-core` 不读取 Puppeteer 配置文件与环境变量中的下载选项，需自行管理浏览器路径。

## 适应人群

- 需要在 Node.js/TypeScript 中编写爬虫、截图、PDF 导出或表单自动化脚本的后端或全栈工程师。
- 维护基于 Chrome DevTools Protocol 的 E2E 测试、视觉回归或 CI 冒烟流水线的前端/测试工程师。
- 评估浏览器自动化底座（含 MCP/Agent 场景）的技术负责人，或从 Puppeteer 迁移到 Playwright/Selenium 的选型对比者。

## 如何使用

### 前置条件

- Node.js 18+（以 [官方 Troubleshooting](https://pptr.dev/troubleshooting) 与当前 major 版本要求为准；过旧 Node 可能导致模块解析错误）。
- 磁盘空间：安装 `puppeteer` 会下载 Chrome for Testing（缓存默认在 `~/.cache/puppeteer`）。
- Linux 无头环境常需额外系统依赖（字体、沙箱相关库）；Docker 场景见官方 [Docker 指南](https://pptr.dev/guides/docker)。

### 安装方式

**方式一：完整包（含浏览器下载）**

```bash
npm i puppeteer
```

**方式二：仅库，不自动下载浏览器**

```bash
npm i puppeteer-core
```

若 npm/pnpm/Yarn/Bun 等包管理器**默认阻止依赖 install 脚本**，安装后需手动下载浏览器：

```bash
npx puppeteer browsers install
```

npm 用户也可在 `package.json` 中为 `puppeteer` 配置 `allowScripts` 以恢复 postinstall 下载（见 [README 说明](https://github.com/puppeteer/puppeteer#installation)）。

### 首次运行

创建 `demo.mjs`（或 TypeScript 等价文件）：

```js
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();
```

执行：

```bash
node demo.mjs
```

有界面调试可将 `launch` 改为 `{ headless: false }`。

### 验证是否成功

- 命令退出码为 0，控制台打印目标页面标题（如 `Example Domain`）。
- 无 `Could not find expected browser locally` 等浏览器缺失报错。
- 可选：运行 README 中的完整示例（含 `locator` 与键盘交互），确认 API 与本地 Chrome 版本匹配。

### 常见坑 / 注意事项

- **Install 脚本被拦截**：现代包管理器常默认禁用 postinstall，导致运行时找不到浏览器；务必执行 `npx puppeteer browsers install` 或配置 `allowScripts`。
- **缓存目录不可写**：CI/打包场景若 home 目录不可用，设置 `PUPPETEER_CACHE_DIR` 或在 `.puppeteerrc.js` 中指定 `cacheDirectory`，并重新安装或手动 install browsers。
- **Linux 沙箱与 root**：在 Docker 或 root 用户下可能需要 `launch({ args: ['--no-sandbox', '--disable-setuid-sandbox'] })`；生产环境应优先修复依赖与权限，而非长期关闭沙箱。
- **HTTP 站点导航报错**：Chrome for Testing 可能启用 HTTPS-First 相关特性，访问 HTTP URL 时出现 `net::ERR_BLOCKED_BY_CLIENT`；可按 [Troubleshooting](https://pptr.dev/troubleshooting) 禁用对应 feature 或改用 HTTPS。
- **Windows 企业策略**：若 Chrome 策略强制扩展，默认 `--disable-extensions` 可能导致启动失败，可设 `enableExtensions: true`。
- **与 Playwright 选型**：需要内置 test runner、trace、多浏览器矩阵时，可并行评估 Playwright；Puppeteer 更适合轻量脚本与 DevTools 深度集成场景。

---

# UI UX Pro Max

> 面向 AI 编程助手的 UI/UX 设计智能 Skill，内置 67 种风格、161 套配色与行业推理规则，一键生成完整设计系统。

- 页面：https://www.niceshare.site/github/ui-ux-pro-max-skill/
- 仓库：https://github.com/nextlevelbuilder/ui-ux-pro-max-skill
- 官网：https://www.uupm.cc/
- 语言：Python
- Stars：93874
- 许可证：MIT
- 标签：AI 编程、开发工具、Agent
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

UI UX Pro Max 是一套可安装到 Claude Code、Cursor、Windsurf 等 AI 编程助手的 UI/UX 设计 Skill。v2.0 的核心是 **Design System Generator**：根据你的产品类型与需求，自动推理并输出包含页面结构、视觉风格、配色、字体、动效与反模式清单的完整设计系统，覆盖 Web、移动端与 15 种技术栈。

## 核心特性

- **Design System Generator**：多域并行检索（产品类型、风格、配色、落地页模式、字体配对），经 BM25 排序与行业规则推理后输出可执行的设计系统
- **67 种 UI 风格**：Glassmorphism、Claymorphism、Bento Grid、Dark Mode、AI-Native UI 等，含落地页与 BI 仪表盘子类
- **161 套行业配色 + 57 组字体配对**：与 161 种产品类型一一对应，附 Google Fonts 导入建议
- **99 条 UX 指南 + 25 种图表类型**：覆盖无障碍、触控、性能、表单反馈等优先级规则
- **15 种技术栈指引**：React、Next.js、Vue、Nuxt、Svelte、SwiftUI、Flutter、Tailwind、shadcn/ui 等
- **CLI 一键安装**：`uipro-cli` 支持 Claude、Cursor、Copilot、Codex 等 18+ 平台，亦可全局安装

## 对用户价值

用 AI 写界面时，常见问题是风格随意、配色不搭、缺少无障碍检查，产出像「AI 味」模板。本 Skill 把设计知识库嵌入助手工作流：你只需描述「为美容 SPA 做落地页」或「做金融科技仪表盘」，助手会先检索行业规则、生成设计系统，再按栈规范写代码，并附带交付前检查清单（对比度、hover 状态、响应式断点等）。

## 与替代方案

- 相比 Figma AI 或 v0 等独立设计生成工具，本 Skill 直接在编码助手内激活，设计与实现同会话完成，适合「边聊边写代码」的 Vibe Coding 流程。
- 相比通用 UI 组件库文档（shadcn/ui、Tailwind UI），这里侧重**行业场景推理**（161 条规则）与反模式过滤，而非单纯罗列组件。
- 相比手写 Cursor Rules 约束视觉风格，本仓库提供可搜索的数据库与 Python 检索脚本，维护成本更低；但若你需要品牌定制设计系统而非行业模板，仍需人工 override。
- 搜索脚本依赖 Python 3.x；纯后端任务无需安装此 Skill。

## 适应人群

- 用 Claude Code / Cursor 做前端或全栈，希望界面更专业、少踩 UX 反模式的开发者。
- 需要快速产出落地页、SaaS 仪表盘、电商或移动端 MVP 的独立开发者与小团队。
- 正在搭建多平台 AI 编程工作流、希望统一 UI 质量基线的平台或效率型用户。

## 如何使用

### 前置条件

- Node.js 环境（用于安装 `uipro-cli`）。
- **Python 3.x**（Skill 内置搜索与设计系统推理脚本依赖；macOS 可用 `brew install python3`）。
- 已安装目标 AI 助手（Claude Code、Cursor 等）。

### 安装方式

**方式 A：CLI（推荐）**

```bash
npm install -g uipro-cli
cd /path/to/your/project
uipro init --ai cursor      # 或 claude / windsurf / copilot / codex 等
```

全局安装（所有项目可用）：

```bash
uipro init --ai cursor --global
```

**方式 B：Claude Code 插件市场**

```
/plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill
/plugin install ui-ux-pro-max@ui-ux-pro-max-skill
```

其他常用命令：

```bash
uipro versions    # 查看可用版本
uipro update        # 更新到最新版
uipro uninstall     # 卸载（自动检测平台）
```

### 首次运行

安装后，在支持 Skill 自动激活的平台（Claude Code、Cursor、Windsurf 等）直接用自然语言发起 UI 任务，例如：

```
为我的 SaaS 产品做一个落地页
```

在 Kiro、Copilot、Roo Code 等平台需使用斜杠命令：

```
/ui-ux-pro-max 为我的 SaaS 产品做一个落地页
```

### 验证是否成功

- 项目目录出现对应平台的 Skill 文件（如 `.cursor/skills/` 或 `~/.cursor/skills/`）。
- 发起 UI 相关请求后，助手应输出设计系统摘要（Pattern、Style、Colors、Typography、Anti-patterns）。
- 运行 `python3 --version` 确认 Python 可用；若检索脚本报错，检查 PATH 与 Python 安装。

### 常见坑 / 注意事项

- **Python 是硬性依赖**：未安装 Python 3 时设计系统检索会失败，务必先 `python3 --version` 验证。
- **平台差异**：Trae 需先切换到 SOLO 模式；Copilot / Kiro / Roo Code 使用 `/ui-ux-pro-max` 斜杠命令而非自动激活。
- **离线安装**：网络受限时可用 `uipro init --offline` 使用内置资源包。
- **贡献者开发**：源码在 `src/ui-ux-pro-max/`，修改后需同步到 `cli/assets/` 并用 `bun run build` 测试 CLI，详见仓库 CLAUDE.md。

---

# nvm

> POSIX Shell 实现的 Node.js 版本管理器，按项目或 Shell 会话切换多版本运行时。

- 页面：https://www.niceshare.site/github/nvm/
- 仓库：https://github.com/nvm-sh/nvm
- 语言：Shell
- Stars：93872
- 许可证：MIT
- 标签：开发工具、CLI、自动化
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

nvm（Node Version Manager）是用 POSIX 兼容 Shell 脚本实现的 Node.js 版本管理器，按用户、按 Shell 会话安装与调用。它可在 Unix、macOS 以及 Windows WSL 上运行，通过 `nvm install` / `nvm use` 快速安装并切换不同 Node 版本，并支持 `.nvmrc` 文件与 LTS 别名，是 Node 生态中最广泛使用的版本管理方案之一。

## 核心特性

- **多版本并存与切换**：`nvm install`、`nvm use`、`nvm run`、`nvm exec` 在同一机器上管理多个 Node 版本，无需全局覆盖
- **LTS 与别名支持**：`nvm install --lts`、`nvm use lts/*` 等命令对齐 Node 官方 LTS 发布节奏；可自定义版本别名
- **`.nvmrc` 项目约定**：在项目根目录放置 `.nvmrc` 声明目标版本，配合 Shell 集成可进入目录自动切换
- **全局包迁移**：`--reinstall-packages-from` 在升级 Node 时迁移已安装的全局 npm 包
- **镜像与离线安装**：支持 `NVM_NODEJS_ORG_MIRROR` 等环境变量指向二进制镜像，适合内网或国内网络环境

## 对用户价值

不同 Node 项目常锁定不同大版本（Legacy 维护、LTS 生产、Current 尝鲜），系统级单一安装难以兼顾。nvm 让每位开发者在同一台机器上并行维护多版本，并在切换目录或 Shell 时自动对齐项目要求，减少「版本不对导致构建失败」的摩擦。对团队而言，`.nvmrc` 可与 CI 脚本共用同一版本声明，降低本地与流水线环境漂移。

## 与替代方案

- 相比 **[fnm](https://github.com/Schniz/fnm)**，nvm 社区体量更大、文档与 Stack Overflow 答案更丰富；fnm 用 Rust 实现，启动与切换速度更快，且支持原生 Windows，适合对性能或跨平台有一致需求的用户。
- 相比 **[n](https://github.com/tj/n)**，nvm 功能更完整（`.nvmrc`、LTS 别名、全局包迁移、Docker 集成文档）；n 更轻量，适合只需简单切换、不介意功能面的个人用户。
- 相比 **[Volta](https://volta.sh/)**，nvm 是纯 Shell 脚本、无额外二进制依赖；Volta 提供项目级 pin 与工具链（npm/yarn）统一管理，体验更「开箱即用」，但生态与可定制性路径不同。
- 相比 **[asdf](https://asdf-vm.com/)**，nvm 专注 Node.js；asdf 通过插件管理多语言运行时，适合已用 asdf 统一 Python/Ruby/Node 等版本的全栈团队。
- **边界说明**：nvm **不支持原生 Windows**（需 WSL）；Docker 非交互 Shell 需额外配置 `BASH_ENV` 或 `source nvm.sh`，详见官方 README。

## 适应人群

- 同时维护多个 Node 项目、需要在 LTS 与 Current 之间频繁切换的全栈与前端工程师。
- 希望用 `.nvmrc` 统一团队本地与 CI Node 版本的技术负责人。
- 在 macOS / Linux / WSL 上工作、偏好 Shell 原生工具链、不想引入额外二进制的开发者。

## 如何使用

### 前置条件

- 操作系统：Unix、macOS，或 **Windows WSL**（不支持原生 Windows CMD/PowerShell）。
- Shell：任意 POSIX 兼容 Shell（bash、zsh、dash、ksh 等）。
- 安装脚本依赖 `curl` 或 `wget`，以及 `git`（用于 clone 仓库到 `~/.nvm`）。

### 安装方式

**一键安装（推荐）：**

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash
```

或使用 wget：

```bash
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash
```

安装完成后**重新打开终端**，或手动加载：

```bash
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
```

**升级 nvm 本身**：重新运行上述 install 脚本即可。

### 首次运行

```bash
nvm install --lts
nvm use --lts
node -v
npm -v
```

安装指定版本并设为默认：

```bash
nvm install 22
nvm alias default 22
```

在项目根目录创建 `.nvmrc`（示例）：

```bash
echo "22" > .nvmrc
nvm use
```

### 验证是否成功

- `nvm --version` 输出版本号（如 `0.40.5`）。
- `nvm ls` 列出已安装版本，当前激活项前有箭头标记。
- `node -v` 与 `npm -v` 输出与 `nvm use` 所选版本一致。
- `nvm run node --version` 可在不切换当前 Shell 默认版本的情况下验证指定版本。

### 常见坑 / 注意事项

- **Shell 配置未生效**：安装脚本会写入 `~/.bashrc`、`~/.zshrc` 等；若 `nvm: command not found`，检查 profile 是否 source 了 `nvm.sh`，或设置 `PROFILE` 环境变量后重装。
- **原生 Windows 不可用**：请在 WSL 内安装 nvm，或改用 fnm / Volta 等支持 Windows 的工具。
- **Docker / CI 非交互 Shell**：常规 profile 不会被加载，需设置 `BASH_ENV` 或在 ENTRYPOINT 中 `source $NVM_DIR/nvm.sh`；官方 README 提供 Dockerfile 示例。
- **国内下载慢**：可设置 `NVM_NODEJS_ORG_MIRROR` 指向 Node 二进制镜像（如 npmmirror 等）加速 `nvm install`。
- **与系统 Node 冲突**：`nvm deactivate` 可临时恢复 PATH 中的系统 Node；避免与 Homebrew 全局 `node` 混用时 PATH 优先级混乱。

---

# Bun

> 一体化 JavaScript/TypeScript 工具链，集运行时、包管理、测试与打包于一体，可作为 Node.js 的高性能替代。

- 页面：https://www.niceshare.site/github/bun/
- 仓库：https://github.com/oven-sh/bun
- 官网：https://bun.com
- 语言：Rust
- Stars：93326
- 许可证：Other
- 标签：开发工具、CLI、后端
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Bun 是由 [Oven](https://github.com/oven-sh) 维护的一体化 JavaScript/TypeScript 工具链，以单个可执行文件 `bun` 交付。其核心是 **Bun 运行时**——用 Zig 编写、基于 JavaScriptCore，定位为 Node.js 的 drop-in 替代，显著降低启动耗时与内存占用。同一 CLI 还内置兼容 npm 的包管理器、测试运行器、脚本执行器与打包器，让开发、安装、测试与构建尽量收敛到一条命令线。

## 核心特性

- **高性能运行时**：原生支持 TypeScript、JSX 与多种文件类型加载器，无需额外转译配置即可 `bun run index.tsx`
- **一体化 CLI**：`bun install`、`bun test`、`bun run`、`bunx` 覆盖依赖安装、测试、脚本与一次性包执行
- **Node.js 兼容层**：持续完善 `node:*` 模块、CommonJS/ESM 解析与 npm 生态兼容，可在多数现有 Node 项目中低改动接入
- **内置打包与 HTTP 服务**：`Bun.build` 打包前端与全栈资源；`Bun.serve` 提供 HTTP/WebSocket 路由与热更新
- **原生数据与 I/O API**：内置 `bun:sqlite`、`Bun.sql`（PostgreSQL）、`Bun.redis`、`Bun.s3` 等，减少常见后端场景的额外依赖

## 对用户价值

若你厌倦「Node + npm/pnpm + Jest/Vitest + esbuild」的多工具拼装，Bun 把运行时与日常开发命令收进一个二进制，安装与 CI 缓存更简单，本地反馈通常更快。对全栈 TypeScript 团队，从 `bun init` 到 `bun test` 再到 `bun build` 可保持统一工具链；对已有 Node 项目，可先替换 `npm install` 或 `node` 启动路径做渐进迁移，在兼容边界内换取速度与简化配置。代价是部分 Node 原生模块、边缘 API 与企业级 LTS 承诺仍不如 Node.js 成熟，生产落地需对照 [Node.js 兼容文档](https://bun.com/docs/runtime/nodejs-compat) 验证。

## 与替代方案

- 相比 [Node.js](https://nodejs.org/)，Bun 在冷启动、包安装与测试执行上通常更快，工具链更集中；Node.js 生态规模、第三方包验证广度、LTS 发布节奏与企业支持经过更长生产检验，关键业务系统更常选 Node。
- 相比 [Deno](https://deno.com/)，Bun 更强调 npm 生态与 Node 兼容、一体化 dev 体验；Deno 默认权限沙箱与 Web 标准 API 取向更明显，适合对安全隔离有强需求的 greenfield 项目。
- 相比单独使用 [pnpm](https://pnpm.io/) / [Vitest](https://vitest.dev/) / [esbuild](https://esbuild.github.io/)，Bun 用单一运行时承载多角色，减少版本冲突与配置面；若团队已深度定制各工具链或依赖特定插件生态，拆分方案仍可能更灵活。
- 边界说明：Bun 不是容器编排或部署平台；复杂 monorepo、特定 Node 原生扩展或冷门 `node:*` API 需在目标环境实测，不宜假设 100% 兼容。

## 适应人群

- 新建或迁移 TypeScript 全栈/脚本项目，希望用一条 CLI 覆盖安装、运行、测试与打包的个人开发者与小团队。
- 在 CI 中追求更快 `install` 与测试反馈、愿意在兼容范围内尝试 Node 替代运行时的前端与后端工程师。
- 维护 npm 生态项目、需要评估 Bun 作为开发/测试加速器（生产仍用 Node）的技术负责人。

## 如何使用

### 前置条件

- 支持平台：Linux（x64 / arm64）、macOS（x64 / Apple Silicon）、Windows（x64 / arm64）。
- Linux 建议内核 **5.6+**（最低 5.1）；x64 若遇 illegal instruction，参阅 [CPU 要求与 baseline 构建](https://bun.com/docs/installation#cpu-requirements-and-baseline-builds)。
- 已有 Node 项目迁移前，建议阅读 [Node.js 兼容性](https://bun.com/docs/runtime/nodejs-compat) 与项目依赖中的原生模块清单。

### 安装方式

**方式一：官方安装脚本（推荐）**

```bash
curl -fsSL https://bun.com/install | bash
```

**Windows（PowerShell）**

```powershell
powershell -c "irm bun.sh/install.ps1 | iex"
```

**其他方式**

```bash
# npm 全局安装
npm install -g bun

# Homebrew（macOS）
brew tap oven-sh/bun
brew install bun

# Docker
docker pull oven/bun
docker run --rm --init --ulimit memlock=-1:-1 oven/bun
```

升级至最新稳定版：

```bash
bun upgrade
```

### 首次运行

```bash
# 验证 CLI
bun --version

# 新建项目（交互式）
bun init

# 或在现有 package.json 项目中安装依赖
bun install

# 运行入口或 package.json 脚本
bun run index.ts
bun run start
```

### 验证是否成功

```bash
bun --version          # 应输出版本号
bun test               # 若有测试文件，应执行测试套件
bun run index.tsx      # TypeScript/JSX 应能直接运行
```

确认 `~/.bun/bin`（或安装脚本提示的路径）已加入 `PATH`，新开终端后 `which bun` 可找到可执行文件。

### 常见坑 / 注意事项

- **Node API 兼容非 100%**：部分 `node:*` 模块、Worker 行为或原生 addon 可能与 Node 不一致，迁移前在 staging 跑通核心路径。
- **许可证为 Other**：商用前阅读仓库 LICENSE 与法律条款，勿默认等同 MIT。
- **Canary 构建**：`bun upgrade --canary` 跟踪 `main` 最新提交，适合尝鲜，生产环境建议锁定稳定版。
- **Linux 内核与 CPU**：老旧内核或不符合要求的 x64 CPU 可能导致安装后无法启动，优先对照官方安装文档排查。

---

# Codex

> OpenAI 官方终端编码 Agent，本地运行，支持 CLI、IDE 与桌面应用。

- 页面：https://www.niceshare.site/github/codex/
- 仓库：https://github.com/openai/codex
- 官网：https://developers.openai.com/codex
- 语言：Rust
- Stars：92155
- 许可证：Apache-2.0
- 标签：AI 编程、Agent、CLI
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Codex 是 OpenAI 推出的轻量级编码 Agent，可在本地终端运行，读取项目上下文并通过自然语言驱动读文件、改代码与执行命令。除 CLI 外，还提供 IDE 扩展（VS Code、Cursor、Windsurf）、桌面应用（`codex app`）与云端 Codex Web 等多种入口。本仓库以 Apache-2.0 开源，承载 CLI 核心实现与贡献指南，适合希望把 OpenAI Agent 能力接入日常开发工作流的用户。

## 核心特性

- **终端原生 Agent**：在项目目录运行 `codex`，用对话完成跨文件编辑与命令执行
- **多入口形态**：CLI、IDE 扩展、桌面应用与 [Codex Web](https://chatgpt.com/codex) 云端 Agent，覆盖不同工作习惯
- **ChatGPT 账户集成**：支持通过 ChatGPT 登录，纳入 Plus、Pro、Business、Edu 或 Enterprise 计划使用
- **API Key 模式**：也可配置 API Key 接入，需按官方文档完成额外鉴权设置
- **多平台安装**：官方脚本、npm、Homebrew 或 GitHub Release 二进制，覆盖 macOS、Linux 与 Windows

## 对用户价值

Codex 把 OpenAI 的编码 Agent 能力收敛到本地终端与常用 IDE，比纯 Web 聊天更贴近真实仓库上下文。对于已订阅 ChatGPT 的开发者，它提供与 OpenAI 生态对齐的官方编码体验；Apache-2.0 许可也便于团队审阅源码、参与贡献或评估长期接入成本。

## 与替代方案

- 相比 **Claude Code**，Codex 绑定 OpenAI / ChatGPT 生态，多入口（CLI、IDE、桌面、Web）覆盖更全；Claude Code 则深度对齐 Anthropic 模型与 GitHub @claude 工作流。
- 相比 **OpenCode**，Codex 是 OpenAI 官方产品，账户与计费走 ChatGPT 计划；OpenCode 完全开源且模型无关，适合自由切换 75+ 提供商。
- 相比 **Aider**，Codex 自主性更强、产品形态更完整；Aider 更轻量，强调逐 diff 结对与多模型切换灵活性。
- 若仅需 IDE 内补全而非 Agent 任务，**Continue** 或 **Copilot** 可能更轻量。

## 适应人群

- 已订阅 ChatGPT Plus/Pro 或企业方案、希望把官方 Agent 接入终端或 IDE 的开发者。
- 习惯 Cursor、VS Code 或 Windsurf，想在编辑器内直接使用 OpenAI 编码 Agent 的工程师。
- 需要评估 OpenAI 官方本地 Agent 能力、并关注 Apache-2.0 开源实现的团队。

## 如何使用

### 前置条件

- macOS、Linux 或 Windows 运行环境。
- 有效的 ChatGPT 账户（Plus、Pro、Business、Edu 或 Enterprise），或已配置可用的 OpenAI API Key。
- 建议在已有 Git 管理的项目目录中试用，便于审查与回滚 Agent 改动。

### 安装方式

**macOS / Linux（推荐）：**

```bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```

**Windows（推荐）：**

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```

**其他方式：**

```bash
# npm
npm install -g @openai/codex

# Homebrew（macOS）
brew install --cask codex
```

也可从 [GitHub Releases](https://github.com/openai/codex/releases/latest) 下载对应平台二进制（如 `codex-aarch64-apple-darwin.tar.gz`）。

### 首次运行

进入目标项目目录，执行：

```bash
codex
```

首次启动选择 **Sign in with ChatGPT** 完成登录；若使用 API Key，请参考 [官方鉴权文档](https://developers.openai.com/codex/auth#sign-in-with-an-api-key) 完成配置。用自然语言描述一个小任务（如解释模块、补充测试或整理提交），观察 Agent 如何读取文件并提出改动。

### 验证是否成功

确认 `codex` 命令可启动、能访问项目文件，且对话中可触发读/写与命令执行。若使用 IDE 扩展，可在 [官方 IDE 文档](https://developers.openai.com/codex/ide) 查阅安装步骤并验证编辑器内 Agent 可用。

### 常见坑 / 注意事项

- Agent 可执行终端命令，首次试用应限制任务范围并审查高风险操作。
- API Key 模式与 ChatGPT 登录的计费、配额策略不同，接入前请阅读 [Codex 文档](https://developers.openai.com/codex) 与 ChatGPT 计划说明。
- 桌面体验可运行 `codex app` 或访问 [Codex App 页面](https://chatgpt.com/codex?app-landing-page=true)；云端 Agent 请使用 [chatgpt.com/codex](https://chatgpt.com/codex)。
- 从 GitHub Release 下载二进制后，解压文件名含平台标识，通常需重命名为 `codex` 再放入 PATH。

---

# Svelte

> 编译型前端框架，将声明式组件编译为高效 DOM 更新代码，无虚拟 DOM 运行时，主打简洁与性能。

- 页面：https://www.niceshare.site/github/svelte/
- 仓库：https://github.com/sveltejs/svelte
- 官网：https://svelte.dev
- 语言：JavaScript
- Stars：87322
- 许可证：MIT
- 标签：开发工具、前端、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Svelte 是由 [Svelte 团队](https://svelte.dev) 维护的编译型前端 UI 框架：你在 `.svelte` 文件中用 HTML、CSS 与 JavaScript 编写声明式组件，构建时由编译器生成针对 DOM 的精确更新逻辑，而非在浏览器中运行庞大的运行时与虚拟 DOM diff。Svelte 5 引入 Runes 响应式原语，让状态与副作用更直观；完整应用通常搭配官方全栈框架 [SvelteKit](https://svelte.dev/docs/kit) 使用。本仓库即 Svelte 编译器与核心运行时源码。

## 核心特性

- **编译时优化**：将组件编译为精简 JavaScript，减少包体积与运行时开销，更新 DOM 时尽量做最小必要变更
- **单文件组件**：`.svelte` 文件内聚模板、样式与逻辑，支持 scoped CSS，学习曲线相对平缓
- **Runes 响应式模型**（Svelte 5）：以 `$state`、`$derived`、`$effect` 等原语描述状态与派生，替代早期基于 `let` 与 `$:` 的写法
- **渐进式采用**：既可嵌入现有页面作为局部组件，也可通过 SvelteKit 构建路由、SSR 与全栈应用
- **丰富官方资源**：交互式 [Tutorial](https://svelte.dev/tutorial)、[Examples](https://svelte.dev/examples)、[REPL](https://svelte.dev/repl) 与完整 [文档](https://svelte.dev/docs/svelte/overview) 降低上手门槛

## 对用户价值

传统框架把大量工作放在浏览器运行时，项目变大后往往面临包体积与更新性能压力。Svelte 把响应式与 DOM 更新逻辑前移到编译阶段，让常见交互组件在同等功能下更轻量，也减少「为了性能而手写优化」的负担。若你维护营销页、仪表盘或需要精细交互的产品界面，Svelte 提供接近原生 Web 技术的写作体验；若需要路由、数据加载与部署一体化，SvelteKit 在同一生态内延伸为全栈方案，避免另选后端框架的割裂感。

## 与替代方案

- 相比 [React](https://react.dev/)，Svelte 不依赖虚拟 DOM 运行时，默认心智模型更接近「写模板 + 状态」；React 生态与招聘市场更成熟，第三方组件与岗位匹配往往更广。
- 相比 [Vue](https://vuejs.org/)，两者都强调单文件组件与渐进式接入；Svelte 更强调编译期优化与更少的框架 API 表面，Vue 在 Options/Composition API 与周边工具链上积累更深。
- 相比 [Angular](https://angular.dev/)，Svelte 更轻量、约束更少，适合小团队快速迭代；Angular 提供开箱即用的完整企业级框架（依赖注入、表单、路由一体化），大型规范化项目有时更省心。
- 边界说明：本仓库聚焦 **UI 编译器与核心库**；生产级应用的路由、构建与部署请优先参考 [SvelteKit](https://github.com/sveltejs/kit) 与[官方文档](https://svelte.dev/docs/kit)，勿将仅安装 `svelte` 等同于完整应用脚手架。

## 适应人群

- 希望用更少样板代码构建交互界面，并关注首屏体积与运行时性能的前端工程师。
- 已有 React/Vue 经验，正在评估迁移成本或在新项目中试用编译型框架的技术负责人。
- 需要单文件组件、scoped 样式与官方教程/REPL 支持，快速从原型到可维护组件库的产品与全栈开发者。

## 如何使用

### 前置条件

- Node.js 18+（以 [SvelteKit 文档](https://svelte.dev/docs/kit) 当前要求为准）。
- npm、pnpm 或 Yarn 等包管理器。
- 仅体验语法可使用浏览器 [REPL](https://svelte.dev/repl)，无需本地环境；正式项目推荐通过 SvelteKit 脚手架创建。

### 安装方式

**方式一：新建 SvelteKit 应用（官方推荐，适合完整项目）**

```bash
npx sv create my-app
cd my-app
npm install
```

使用 pnpm 时，在 `sv create` 向导中选择 pnpm，或于项目目录执行 `pnpm install`。

**方式二：在现有 Vite 等项目中添加 Svelte 编译器**

```bash
npm install -D svelte @sveltejs/vite-plugin-svelte
```

具体 `vite.config` 与 `svelte.config` 写法见 [Svelte 文档 - Getting started](https://svelte.dev/docs/svelte/getting-started)。

### 首次运行

在 SvelteKit 项目中启动开发服务器：

```bash
npm run dev
```

终端会输出本地预览地址（默认 `http://localhost:5173`）。在 `src/routes/` 下编辑页面即可看到热更新。若仅需快速体验语法，可打开 [Tutorial](https://svelte.dev/tutorial) 或 [REPL](https://svelte.dev/repl) 无需本地安装。

### 验证是否成功

- 浏览器打开 dev server URL，默认欢迎页可正常渲染且无控制台报错。
- 修改 `src/routes/+page.svelte` 中的文案或按钮事件，保存后页面应热更新。
- 运行 `npm run build` 成功产出生产构建；`npm run preview` 可本地预览构建结果。

### 常见坑 / 注意事项

- **Svelte 与 SvelteKit 分工**：`svelte` 包提供编译器与组件运行时；路由、SSR、适配器与 `+page.server` 等能力属于 SvelteKit，选型时勿混淆。
- **版本与迁移**：Svelte 5 的 Runes 与 Svelte 4 写法差异较大，维护旧项目请对照 [迁移指南](https://svelte.dev/docs/svelte/v5-migration-guide)；升级前阅读 [CHANGELOG](https://github.com/sveltejs/svelte/blob/main/packages/svelte/CHANGELOG.md)。
- **生态与岗位**：组件库与招聘市场体量通常小于 React，引入前评估团队技能与第三方依赖可用性。
- **社区支持**：问题可查 [文档](https://svelte.dev/docs)、[Discord](https://svelte.dev/chat) 或 GitHub Issues；`.dev` 域名偶发本地 DNS 问题可参考 README 中的说明。

---

# uv

> 极快的 Rust 版 Python 包与项目管理器，可替代 pip、Poetry、pyenv 等一整套工具。

- 页面：https://www.niceshare.site/github/uv/
- 仓库：https://github.com/astral-sh/uv
- 官网：https://docs.astral.sh/uv
- 语言：Rust
- Stars：86573
- 许可证：Apache-2.0
- 标签：开发工具、CLI、自动化
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

uv 是由 Astral（Ruff 与 ty 的出品方）用 Rust 编写的 Python 包与项目管理器，目标是用一个工具替代 `pip`、`pip-tools`、`pipx`、`poetry`、`pyenv`、`virtualenv` 等常见组件。它提供项目级 lockfile、工作区、脚本内联依赖、Python 版本管理与 pip 兼容接口，在缓存命中场景下安装速度可比 pip 快 10–100 倍，并支持 macOS、Linux 与 Windows。

## 核心特性

- **一站式工具链**：项目管理（`uv init` / `add` / `sync` / `lock`）、脚本运行、CLI 工具（`uvx`）、Python 版本安装与切换
- **极速依赖解析与安装**：Rust 实现 + 全局缓存去重，warm cache 下常见操作可达毫秒级
- **通用 lockfile**：跨平台可复现的依赖锁定，支持 Cargo 风格 workspaces
- **脚本内联元数据**：单文件脚本可通过 `uv add --script` 声明依赖，`uv run` 自动创建隔离环境
- **pip 兼容层**：`uv pip compile` / `sync` / `venv` 等命令可渐进迁移现有 pip 工作流

## 对用户价值

uv 把「装 Python、建虚拟环境、锁依赖、跑脚本、装 CLI 工具」收敛到一个二进制里，显著减少工具碎片化与等待时间。对已有 pip/requirements 流程的团队，可通过 `uv pip` 接口无痛提速；对新项目，可直接采用 `pyproject.toml` + `uv.lock` 的现代项目管理方式。全局缓存还能节省磁盘，适合多项目并行开发。

## 与替代方案

- 相比 **pip + venv + pip-tools**，uv 速度更快、功能更全（含 Python 版本管理与工具安装），且提供等价的 `uv pip` 迁移路径。
- 相比 **Poetry**，两者都强调项目与 lockfile 管理；uv 额外覆盖 pyenv/pipx 场景，性能更突出，Poetry 则在部分生态插件与历史项目迁移上更成熟。
- 相比 **pipx**，uv 的 `uv tool install` / `uvx` 提供类似的一次性/持久化工具运行能力，并与其他 uv 子命令共享缓存。
- 相比 **rye**，uv 由 Astral 持续投入、社区体量更大；若团队已深度绑定 rye 工作流，迁移需评估 lockfile 与脚本差异。

## 适应人群

- 日常维护多个 Python 项目、厌倦 pip 慢速与工具拼凑的开发者。
- 希望统一 CI/CD 依赖安装流程、缩短构建时间的工程团队。
- 从 pip/requirements 渐进迁移、或新建项目想直接采用现代 Python 工具链的技术负责人。

## 如何使用

### 前置条件

- macOS、Linux 或 Windows 任一受支持平台。
- 网络可访问 PyPI（或已配置私有 index / mirror）。
- 无需预装 Rust；独立安装器也不依赖本机已有 Python。

### 安装方式

**macOS / Linux（推荐）：**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows：**

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**通过 PyPI：**

```bash
pip install uv
# 或
pipx install uv
```

安装后可用 `uv self update` 自更新。更多方式见 [官方安装文档](https://docs.astral.sh/uv/getting-started/installation/)。

### 首次运行

**新建项目：**

```bash
uv init myproject
cd myproject
uv add ruff
uv run ruff check
```

**在现有 requirements 流程中试用：**

```bash
uv venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt
```

### 验证是否成功

执行 `uv --version` 应输出版本号。`uv run python --version` 或 `uvx cowsay hello` 能正常完成即表示核心路径可用。项目管理场景下 `uv lock` 与 `uv sync` 无报错即表示环境与 lockfile 一致。

### 常见坑 / 注意事项

- **渐进迁移**：`uv pip` 与 `uv add`/`sync` 是两套入口，混用时需明确团队约定，避免 lockfile 与 requirements 双轨漂移。
- **私有源配置**：企业内网 PyPI 需在 `pyproject.toml` 或环境变量中配置 index，详见 [文档](https://docs.astral.sh/uv/configuration/indexes/)。
- **许可证**：项目采用 Apache-2.0 与 MIT 双许可，贡献默认按双许可处理。
- **生产就绪**：官方声明 uv 已稳定并广泛用于生产，但大版本升级前仍建议阅读 [版本策略](https://docs.astral.sh/uv/reference/versioning/) 与 Release Notes。

---

# Zed

> Rust 原生高性能代码编辑器，内置 AI Agent 与多人协作，出自 Atom 与 Tree-sitter 团队。

- 页面：https://www.niceshare.site/github/zed/
- 仓库：https://github.com/zed-industries/zed
- 官网：https://zed.dev
- 语言：Rust
- Stars：85597
- 许可证：GPL-3.0-or-later
- 标签：开发工具、AI 编程、Agent
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Zed 是由 Atom 与 Tree-sitter 原班团队用 Rust 打造的下一代代码编辑器，强调极低延迟的编辑体验与内置多人协作。它不只是更快的 IDE：官方已把 Zed Agent、并行 Agent 线程、MCP 工具链与外部 Agent（ACP）整合进同一工作区，适合把日常编码、结对调试与 AI 辅助开发放在同一套界面里完成。

## 核心特性

- **Rust 原生性能**：GPU 加速渲染与 Tree-sitter 语法分析，大仓库滚动与跳转响应快
- **多人协作**：频道、联系人、私密通话与共享编辑，支持远程结对
- **Zed Agent**：内置 Agent 面板，可接 API Key、订阅、网关或本地模型，并支持 Skills、Instructions 与 MCP
- **并行 Agent**：Threads Sidebar 中同时跑多条 Agent 或 Terminal Threads（终端内 Agent CLI）
- **AI 编辑辅助**：Inline Assistant、Edit Prediction 与 Git 提交信息生成
- **跨平台**：macOS、Linux、Windows 官方安装包；支持远程开发与 Dev Containers

## 对用户价值

Zed 解决的是「编辑器慢、协作靠屏幕共享、AI 工具散落各处」的割裂感：原生性能让日常导航与编辑更顺，协作能力让结对不必再切 Zoom + VS Code，而 Agent 与 MCP 又减少在终端、插件与 IDE 之间来回切换。对重视响应速度与工作流一体化的开发者，它是比 Electron IDE 更轻、比纯终端编辑器更完整的 GUI 方案。

## 与替代方案

- 相比 **VS Code**，Zed 是 Rust 原生而非 Electron，启动与滚动通常更快；协作与 Agent 为内置能力，而非依赖大量扩展拼装。
- 相比 **Cursor** 等 AI 优先 IDE，Zed 开源可审计（GPL-3.0-or-later），模型接入路径更灵活，但生态与插件数量仍不及 VS Code 系。
- 相比 **Neovim**，Zed 提供图形界面、内置协作与 Agent 面板；若你重度依赖 Vim 插件生态，迁移成本需评估（Zed 支持 Vim/Helix 键位模式）。
- 若只需轻量补全、不需要完整 IDE 或协作，**Continue** 插件或 **Copilot** 可能更省事。

## 适应人群

- 对大仓库编辑延迟敏感、希望换用原生编辑器的开发者。
- 需要实时结对或频道协作的小团队与远程工程师。
- 想在单一 IDE 内配置 Agent、MCP 与并行任务流的 AI 编程用户。

## 如何使用

### 前置条件

- **macOS** 12+（Monterey 及以上协作功能更完整；旧版 macOS 屏幕共享能力受限）
- **Linux** 或 **Windows** 满足 [官方平台要求](https://zed.dev/docs/linux)（Linux 需合适 GPU 驱动）
- 使用 AI 功能时需准备模型 API Key、订阅或本地模型端点（见 [AI Quick Start](https://zed.dev/docs/ai/quick-start)）

### 安装方式

- **macOS（Homebrew）**：

```sh
brew install --cask zed
```

- **Linux（官方脚本）**：

```sh
curl -f https://zed.dev/install.sh | sh
```

- **Windows（winget）**：

```sh
winget install -e --id ZedIndustries.Zed
```

- 也可从 [zed.dev/download](https://zed.dev/download) 直接下载安装包；各平台包管理器说明见 [安装文档](https://zed.dev/docs/installation)。

### 首次运行

启动 Zed 后打开一个本地项目，熟悉 Command Palette 与 Project Panel。若需 AI，在设置中配置 [LLM Provider](https://zed.dev/docs/ai/llm-providers)，打开 Agent Panel 发起一次小任务（如解释文件或生成测试）。

### 验证是否成功

确认编辑器能正常索引项目、LSP 诊断可用；若启用 AI，Agent 能读取上下文并返回 diff 或终端输出。协作功能需登录 Zed 账户后邀请联系人或加入频道验证。

### 常见坑 / 注意事项

- 源码以 **GPL-3.0-or-later** 为主（部分组件 Apache-2.0）；商业分发或二次开发需留意许可边界。
- AI 与 Zed 托管模型涉及账户、计费与数据策略，部署前阅读 [AI Privacy](https://zed.dev/docs/ai/privacy-and-security)。
- 从 VS Code 迁移可参考 [官方迁移指南](https://zed.dev/docs/migrate/vs-code)；扩展生态仍在成长，关键插件缺失时需提前核对。
- 自编译见仓库 `docs/src/development/`，依赖 Rust 工具链与平台特定构建步骤，门槛高于直接安装包。

---

# Caveman

> Claude Code 等 AI 编程 Agent 的口语压缩 Skill，输出 token 约省 65%，代码原样保留。

- 页面：https://www.niceshare.site/github/caveman/
- 仓库：https://github.com/JuliusBrussee/caveman
- 官网：https://caveman.so/
- 语言：JavaScript
- Stars：83616
- 许可证：MIT
- 标签：AI 编程、开发工具、Agent
- 收录：2026-07-04（更新于 2026-07-04）

## 项目介绍

Caveman 是一款面向 **AI 编程 Agent** 的 Skill / 插件：让 Claude Code、Codex、Gemini、Cursor、Windsurf、Cline、Copilot 等 30+ 工具用「穴居人式」短句作答，**砍掉寒暄与冗余解释**，但代码块、命令行与错误信息 **逐字节保留**。官方基准显示平均 **输出 token 减少约 65%**（10 组任务 22%–87%），技术结论不丢，阅读更快；另有 `/caveman-compress` 可压缩 `CLAUDE.md` 等记忆文件，后续会话 **输入 token 长期省约 46%**。

## 核心特性

- **一键多 Agent 安装**：`install.sh` / `install.ps1` 自动扫描本机 Agent 并写入对应 skill / plugin / rule 路径，约 30 秒完成
- **六级压缩档位**：`lite` / `full`（默认）/ `ultra` / `wenyan`（文言）等，会话内 `/caveman [level]` 切换；保持用户语言，只压风格不翻译
- **配套命令**：`/caveman-commit`（≤50 字 Conventional Commit）、`/caveman-review`（单行 PR 评论）、`/caveman-stats`（会话与累计 token / USD 统计）、`/caveman-compress`（记忆文件压缩）
- **生态扩展**：`caveman-shrink` MCP 中间件压缩 tool 描述；`cavecrew-*` 子 Agent；与 [caveman-code](https://github.com/JuliusBrussee/caveman-code)、[cavemem](https://github.com/JuliusBrussee/cavemem) 等同属「少 token 多干活」工具链
- **本地优先、无遥测**：安装后 skill 仅为 prompt + 本地 hook，`/caveman-stats` 读本地日志，无账号与后端上报（见 [SECURITY.md](https://github.com/JuliusBrussee/caveman/blob/main/SECURITY.md)）

## 对用户价值

长对话里 Agent 常「解释过多、代码过少」，输出 token 堆在寒暄与重复论证上。Caveman 把 **口语层** 压短，适合按 token 计费的 API 用户、终端窄屏阅读，以及希望 **更快扫完结论再动手改代码** 的开发者。Claude Code 上 hook 可在首条消息起默认启用；状态栏可显示累计节省 `[CAVEMAN] ⛏ 12.4k`。需注意：skill 本身每轮约增 1–1.5k **输入** token，已很简洁的任务可能净收益为负——官方 [HONEST-NUMBERS.md](https://github.com/JuliusBrussee/caveman/blob/main/docs/HONEST-NUMBERS.md) 有完整说明。

## 与替代方案

- 相比手动写「请简短回答」等 **一次性 prompt**，Caveman 提供 **可安装、可统计、可分级** 的 skill + hook，并覆盖 commit / review / 记忆压缩等固定工作流。
- 相比 [caveman-code](https://github.com/JuliusBrussee/caveman-code)（全栈终端 Agent、端到端约 2× 省 token），本仓库只改 Agent **怎么说**，不改模型与工具链选型；二者可叠加使用。
- 相比 [Continue](https://github.com/continuedev/continue)、[Cline](https://github.com/cline/cline) 等 **IDE 内置模型与 UI**，Caveman 是 **跨 Agent 的压缩层**，不替代编辑器本身；在 Cursor / Cline 上通过 `npx skills add` 接入。
- 相比 [Superpowers](https://github.com/obra/superpowers) 等 **流程与 TDD 技能包**，Caveman 专注 **token 效率与可读性**，不编排 brainstorm / plan 等阶段；定位互补而非互斥。
- **`wenyan` 模式** 故意用文言压缩，与其他档位「保持用户语言」策略不同，选用前需确认团队阅读习惯。

## 适应人群

- 日常使用 **Claude Code、Cursor、Codex、Gemini CLI** 等 AI 编程 Agent 的开发者。
- 按 **输出 token 计费**、希望在不牺牲代码与命令准确性的前提下降低账单的用户。
- 维护较大 **`CLAUDE.md` / 项目记忆文件**、想长期削减每会话上下文体积的团队。

## 如何使用

### 前置条件

- **Node.js ≥ 18**（部分安装路径依赖 `npx skills`）。
- 本机已安装至少一种支持的 Agent（Claude Code、Cursor、Codex、Gemini CLI、Cline 等）；完整矩阵见 [INSTALL.md](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md)。
- macOS / Linux / WSL / Git Bash，或 Windows PowerShell 5.1+。

### 安装方式

**推荐：一键扫描本机所有 Agent 并安装**

```bash
# macOS · Linux · WSL · Git Bash
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash
```

```powershell
# Windows · PowerShell 5.1+
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1 | iex
```

**单 Agent 示例**（更多见 INSTALL.md）：

```bash
# Claude Code plugin
claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman

# Cursor / Windsurf / Cline / Codex 等
npx skills add JuliusBrussee/caveman -a cursor
```

OpenClaw 专用：

```bash
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash -s -- --only openclaw
```

### 首次运行

- 安装完成后在 Agent 中输入 **`/caveman`** 或说 **「talk like caveman」** 启用；说 **「normal mode」** 关闭。
- Claude Code、Codex、Gemini 上部分路径 **首条消息即默认启用**，无需每次敲命令。
- 可选切换档位：`/caveman lite` | `full` | `ultra` | `wenyan`。

### 验证是否成功

- 让 Agent 解释一个技术问题，对比启用前后 **回复长度**；代码块与命令应与原文一致。
- 运行 **`/caveman-stats`**，查看本会话与累计节省 token / USD；Claude Code 状态栏应出现 `[CAVEMAN] ⛏ …`（可用 `CAVEMAN_STATUSLINE_SAVINGS=0` 关闭）。
- 对 `CLAUDE.md` 试跑 **`/caveman-compress`**，确认路径与代码片段未被改写。

### 常见坑 / 注意事项

- **65% 主要指输出 token**；输入与 reasoning 不变，且 skill 自带上下文会增加输入——短任务可能 **净省为负**，见 [HONEST-NUMBERS.md](https://github.com/JuliusBrussee/caveman/blob/main/docs/HONEST-NUMBERS.md)。
- 安装脚本会访问 GitHub 与各 Agent  registry；离线环境需按 INSTALL.md **手动拷贝 skill 文件**。
- 多 Agent 并存时路径不同，**重复运行 install 安全**；卸载加 `--uninstall`，OpenClaw 仅移除 marker 块与 skill，不删其他 workspace 内容。
- **caveman-code**（`npm install -g @juliusbrussee/caveman-code`）是独立的全栈终端 Agent，与本 skill 仓库不同产品，勿混淆安装目标。

---

# claude-mem

> 跨会话持久记忆插件，自动捕获代理行为、AI 压缩摘要并注入后续上下文。

- 页面：https://www.niceshare.site/github/claude-mem/
- 仓库：https://github.com/thedotmack/claude-mem
- 官网：https://claude-mem.ai
- 语言：JavaScript
- Stars：83233
- 许可证：Apache-2.0
- 标签：AI 编程、Agent、知识管理
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

claude-mem 是由 Alex Newman（thedotmack）维护的**跨会话持久记忆系统**，最初为 Claude Code 设计，现已扩展到 OpenClaw、Codex、Gemini、Hermes、Copilot、OpenCode 等多种 Agent 宿主。它通过生命周期钩子自动捕获工具调用与观察记录，用 AI 生成语义摘要并压缩存储，在新会话启动时按「渐进式披露」策略注入相关上下文，让代理在会话结束或重连后仍能延续对项目的认知。

## 核心特性

- **持久化记忆**：上下文跨会话保留，无需手动复制粘贴历史对话
- **渐进式披露**：分层检索记忆并展示 token 成本，避免一次性灌入过多上下文
- **mem-search 技能与 MCP 搜索**：支持自然语言查询项目历史，三层工作流（search → timeline → get_observations）控制 token 开销
- **Web 查看器**：`http://localhost:37777` 实时浏览记忆流、引用观察 ID、切换稳定版与 Beta 渠道
- **隐私控制**：用 `<private>` 标签排除敏感内容，不写入本地存储
- **混合检索架构**：SQLite + FTS5 关键词搜索，配合 Chroma 向量库做语义检索
- **多宿主安装**：支持 `npx claude-mem install`、Claude Code 插件市场、Gemini CLI / OpenCode 专用参数，以及 OpenClaw 一键脚本

## 对用户价值

AI 编程助手每次开新会话都会「失忆」，重复解释架构决策、踩过的坑和进行中的任务。claude-mem 在后台自动记录并压缩这些观察，下次会话启动时把真正相关的片段注入上下文，减少重复对齐成本。对个人开发者，它相当于给 Agent 装上项目级长期记忆；对团队，本地 SQLite 存储便于审计与隐私控制，不必把完整对话历史交给第三方云服务。

## 与替代方案

- 相比在仓库里手写 `CLAUDE.md` / Cursor Rules 等静态上下文，claude-mem 提供**动态、可检索**的会话记忆，能覆盖工具调用细节与跨天工作轨迹，而非仅描述项目约定。
- 相比 [Mem0](https://github.com/mem0ai/mem0) 等通用 Agent 记忆框架，claude-mem 深度绑定 Claude Code 钩子与 Worker 服务，开箱即用；若你需要跨语言 SDK、云端托管或多租户记忆池，Mem0 等方案更灵活，但集成成本更高。
- 相比依赖 IDE 内置聊天历史或手动导出对话，本方案通过**压缩摘要 + 向量搜索**控制 token 预算，并支持引用 ID 回溯原始观察；代价是需要本地运行 Worker（端口 37777）并配置 AI 模型用于摘要生成。

## 适应人群

- 长期使用 Claude Code、Cursor 或 OpenClaw，在同一代码库上跨多天推进功能的开发者。
- 希望 Agent 记住「上次改了什么、为什么这样设计」而不仅是 README 内容的效率型用户。
- 对数据出境敏感、倾向本地 SQLite 存储与 `<private>` 隐私标签的团队或个人。

## 如何使用

### 前置条件

- **Node.js ≥ 20.0.0**（Windows 需确保 `npm` 在 PATH 中）
- 目标 Agent 宿主：Claude Code（插件支持）、Gemini CLI、OpenCode，或 OpenClaw Gateway
- Bun、uv 会在安装时自动拉取（Worker 与向量搜索依赖）；SQLite 已捆绑
- 摘要生成需配置 AI 提供商（安装向导或 `~/.claude-mem/settings.json` 中设置）

### 安装方式

**Claude Code（推荐）**

```bash
npx claude-mem install
```

或在 Claude Code 会话内：

```text
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
```

**Gemini CLI**

```bash
npx claude-mem install --ide gemini-cli
```

**OpenCode**

```bash
npx claude-mem install --ide opencode
```

**OpenClaw Gateway**

```bash
curl -fsSL https://install.cmem.ai/openclaw.sh | bash
```

> 注意：`npm install -g claude-mem` 仅安装 SDK 库，**不会**注册插件钩子或启动 Worker；请始终使用 `npx claude-mem install` 或 `/plugin` 命令。

### 首次运行

安装后重启 Agent 宿主。Worker 默认监听 `http://localhost:37777`，可在 Web 查看器中确认记忆流是否正常写入。中文用户可在 `~/.claude-mem/settings.json` 设置 `"CLAUDE_MEM_MODE": "code--zh"` 后重启 Claude Code。

### 验证是否成功

- 完成一次含工具调用的会话，结束后再开新会话，应能看到先前上下文的自动注入
- 浏览器访问 `http://localhost:37777`，确认会话与观察记录出现
- 在对话中询问「之前做过什么」，mem-search 技能或 MCP `search` 工具应返回带 ID 的历史索引

### 常见坑 / 注意事项

- 全局 `npm install -g` 不等于完整安装；缺少 Worker 时记忆不会持久化。
- Worker 占用本地端口 37777，多项目或 CI 环境需注意端口冲突与进程管理。
- 敏感内容务必用 `<private>` 包裹，避免写入本地数据库。
- Beta 渠道（如 Endless Mode）可在 Web 查看器 Settings 中切换，稳定性不如主版本。
- 故障排查可让 Claude 调用内置 troubleshoot 技能，或查阅[官方故障排除文档](https://docs.claude-mem.ai/troubleshooting)；Bug 报告可运行 `npm run bug-report`（在插件目录下）。

---

# Vite

> 下一代前端构建工具，开发时原生 ESM 极速冷启动与 HMR，生产构建默认 Rolldown 输出优化静态资源。

- 页面：https://www.niceshare.site/github/vite/
- 仓库：https://github.com/vitejs/vite
- 官网：https://vite.dev
- 语言：TypeScript
- Stars：81548
- 许可证：MIT
- 标签：开发工具、前端、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Vite 是由 [vitejs](https://github.com/vitejs) 维护的下一代前端构建工具，面向现代 Web 项目提供更快、更轻量的开发体验。它由两部分组成：**开发服务器**基于原生 ES 模块，配合依赖预构建实现毫秒级冷启动与极速 HMR；**生产构建**默认使用 [Rolldown](https://rolldown.rs) 打包并输出高度优化的静态资源。本仓库为 Vite 核心、`create-vite` 脚手架及 `@vitejs/plugin-*` 官方插件 monorepo，并通过 Plugin API 与 JavaScript API 提供完整 TypeScript 类型支持。

## 核心特性

- **极速开发服务器**：利用浏览器原生 ESM，跳过传统打包式 dev server 的整包编译，冷启动与热更新响应极快
- **依赖预构建**：使用 esbuild 将 CommonJS/UMD 依赖转为 ESM 并合并请求，兼顾兼容性与加载性能
- **Rolldown 生产构建**：默认 Rolldown 打包，输出 tree-shaking、代码分割与资源优化后的生产产物
- **框架无关与插件生态**：官方提供 Vue、React、Svelte 等模板；社区插件覆盖 SSR、Legacy 浏览器、PWA 等场景
- **完整类型化 API**：`vite.config.ts`、`defineConfig` 与 Plugin/JavaScript API 均提供 TypeScript 类型提示

## 对用户价值

传统 Webpack 开发模式往往在项目变大后，dev server 启动与 HMR 成为日常摩擦。Vite 把「开发时不打包、按需编译」作为默认路径，让本地反馈接近源码编辑速度，同时生产构建仍走成熟打包管线。对团队而言，这意味着更短的 onboarding（`create vite` 即可跑通）、更低的配置负担，以及 Astro、Nuxt、SvelteKit 等主流框架对 Vite 的深度集成——选 Vite 等于对齐当前前端工具链的主流方向。

## 与替代方案

- 相比 [Webpack](https://webpack.js.org/)，Vite 开发阶段无需整包打包，冷启动与 HMR 通常显著更快；Webpack 在复杂自定义 loader/插件链与遗留项目迁移上历史积累更深，大型存量项目切换需评估成本。
- 相比 [Parcel](https://parceljs.org/) 等零配置打包器，Vite 在框架集成、插件市场与生态文档上更成熟，且生产构建已转向 Rolldown；Parcel 适合追求「开箱即用、少配置」的小型项目。
- 相比 [esbuild](https://github.com/evanw/esbuild) 单独使用，Vite 提供完整 dev server、HMR、插件体系与框架模板；esbuild 更适合作为底层转译/压缩工具嵌入自定义流水线。
- 相比 [Next.js](https://nextjs.org/)、[Nuxt](https://nuxt.com/) 等全栈框架内置工具链，Vite 是**通用构建底座**，适合 SPA、组件库、文档站或需要自选路由/状态方案的项目；若产品需要 App Router、SSR 约定式路由等，对应框架往往更自然。
- 边界说明：Vite 不是后端框架或部署平台；Node 服务端渲染需配合框架适配器（如 `@vitejs/plugin-react` + SSR 配置），复杂 monorepo 与微前端场景需额外规划。

## 适应人群

- 新建 React、Vue、Svelte 等 SPA 或组件库，希望快速获得现代 dev/build 体验的前端工程师。
- 维护 Webpack 存量项目、评估迁移到 Vite 以缩短本地反馈与 CI 构建时间的团队。
- 使用 Astro、Vitest 等同生态工具，希望统一 Vite 配置与插件投资的全栈与平台同学。

## 如何使用

### 前置条件

- Node.js 20.19+ 或 22.12+（以 [官方 Getting Started](https://vite.dev/guide/#scaffolding-your-first-vite-project) 当前要求为准；部分模板可能要求更高版本）。
- npm、pnpm、Yarn 或 Bun 等包管理器。
- 可选：浏览器访问 [vite.new](https://vite.new/) 或 [StackBlitz](https://vite.new/vanilla) 在线体验，无需本地安装。

### 安装方式

**方式一：脚手架新建项目（推荐）**

```bash
npm create vite@latest
```

使用 pnpm 时：

```bash
pnpm create vite
```

按提示选择框架（Vanilla、Vue、React、Svelte 等）与 TypeScript 选项。

**方式二：手动安装到现有目录**

```bash
npm install -D vite
```

在 `package.json` 中添加 `"dev": "vite"`、`"build": "vite build"`，并创建 `index.html` 作为入口（见 [官方手动安装指南](https://vite.dev/guide/#manual-installation)）。

### 首次运行

进入项目目录启动开发服务器：

```bash
npm run dev
```

终端会输出本地预览 URL（默认 `http://localhost:5173`）。修改 `src/` 下源码或根目录 `index.html` 后应触发热更新。

### 验证是否成功

- 浏览器打开 dev server URL，页面正常渲染且无控制台阻塞性错误。
- 保存源码后 HMR 应在数百毫秒内反映变更。
- 运行 `npm run build` 成功产出 `dist/`；`npm run preview` 可本地预览生产构建结果。

### 常见坑 / 注意事项

- **Node 版本**：低于官方要求的 Node 版本会导致 create-vite 或 dev server 报错，升级后重试。
- **CommonJS 依赖**：部分 npm 包未提供 ESM 出口时，可能需在 `optimizeDeps` 或 `ssr.noExternal` 中显式配置；查阅 [依赖预构建文档](https://vite.dev/guide/dep-pre-bundling)。
- **路径别名与环境变量**：`@` 别名需在 `vite.config.ts` 的 `resolve.alias` 中声明；客户端可用变量须以 `VITE_` 前缀暴露。
- **Legacy 浏览器**：生产默认面向现代浏览器；需支持旧版浏览器时安装 [@vitejs/plugin-legacy](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy)。
- **求助渠道**：查阅 [vite.dev 文档](https://vite.dev/)、[Vite Discord](https://chat.vite.dev)，或搜索 [awesome-vite](https://github.com/vitejs/awesome-vite) 社区资源。

---

# LobeHub

> 开源 AI 代理运营平台，统一管理多模型对话、插件与知识库（原 Lobe Chat）。

- 页面：https://www.niceshare.site/github/lobechat/
- 仓库：https://github.com/lobehub/lobehub
- 官网：https://lobehub.com
- 语言：TypeScript
- Stars：78864
- 许可证：MIT
- 标签：AI 编程、知识管理、本地模型
- 收录：2026-06-19（更新于 2026-06-19）

## 项目介绍

LobeHub（前身为 Lobe Chat）是开源的现代化 AI 交互平台，支持 OpenAI、Anthropic、Google 等云端模型，也可对接 Ollama 等本地推理服务。它提供插件市场、知识库、语音能力与代理编排，适合作为个人或团队的 AI 入口与「首席代理运营」控制台。

## 核心特性

- 统一界面管理多模型供应商与切换
- 插件系统与 Agent 市场，可扩展工具能力
- 知识库上传与 RAG 对话
- 支持 TTS/STT 与富媒体交互
- Docker / Vercel 等多种部署方式

## 对用户价值

LobeHub 为多模型与多代理场景提供统一界面，避免在不同服务之间反复登录和复制粘贴。插件与知识库适合需要长期积累上下文或接入外部工具的用户；团队可自托管以控制数据与品牌体验。

## 与替代方案

- 相比 Open WebUI，LobeHub 更强调多供应商客户端与 Agent 运营，UI 与插件生态路径不同。
- 相比 ChatGPT 网页版，自托管 LobeHub 可接入私有模型与自定义插件。
- 若只需极简 Ollama 聊天，Open WebUI 或 Ollama 自带界面可能更轻。

## 适应人群

- 需要统一管理多模型访问的个人用户。
- 希望自建团队 AI 聊天前端的工程团队。
- 关注聊天 UI 与 Agent 编排的产品和设计参考者。

## 如何使用

### 前置条件

- Docker 或 Node.js 部署环境。
- 各模型服务商 API 密钥，或本机 Ollama 端点。
- 多用户生产部署建议配置外部数据库（见官方文档）。

### 安装方式

Docker 快速启动（见 [官方仓库 README](https://github.com/lobehub/lobehub)）：

```bash
docker run -d -p 3210:3210 \
  -e OPENAI_API_KEY=your_key \
  --name lobehub \
  lobehub/lobehub
```

也可使用 Vercel 一键部署模板。

### 首次运行

访问本地 `http://localhost:3210`，在设置中配置模型提供方；若使用 Ollama，填写 `http://host.docker.internal:11434` 等端点。

### 验证是否成功

发起对话并切换模型，测试插件或知识库上传是否正常响应。

### 常见坑 / 注意事项

- Docker 内访问宿主机 Ollama 需注意网络与地址配置。
- 多用户与持久化需按文档配置数据库与密钥，勿仅用默认 SQLite 上生产。
- 项目已从 Lobe Chat 品牌演进为 LobeHub，旧文档链接可能跳转，以官方站为准。

---

# Elasticsearch

> 分布式搜索与分析引擎，支持全文检索、日志指标、APM 与向量搜索，Elastic Stack 核心组件。

- 页面：https://www.niceshare.site/github/elasticsearch/
- 仓库：https://github.com/elastic/elasticsearch
- 官网：https://www.elastic.co/products/elasticsearch
- 语言：Java
- Stars：77271
- 许可证：Elastic-2.0 / SSPL
- 标签：开发工具、系统工具、自托管
- 收录：2026-07-03（更新于 2026-07-03）

## 项目介绍

Elasticsearch 是 Elastic 开源 Stack 的核心，面向生产级工作负载提供分布式搜索、分析与可扩展数据存储，并内置向量检索能力。它基于 Lucene，支持近实时全文搜索、结构化日志与指标聚合、APM 与安全事件分析，以及面向 RAG 等 GenAI 场景的语义检索。本仓库为官方源码；日常开发可优先用 Docker 一键脚本或 Elastic Cloud 托管，生产自管部署通常从 [elastic.co 下载页](https://www.elastic.co/downloads/elasticsearch) 获取发行包，而非直接编译 GitHub 镜像。

## 核心特性

- **分布式搜索引擎**：倒排索引与分片副本架构，支持近实时全文检索、聚合分析与地理空间查询
- **统一数据平台**：同一集群可承载日志（ELK）、指标、APM、安全事件与业务搜索等混合负载
- **向量与 AI 集成**：原生向量搜索与混合检索，可对接 RAG、语义搜索与生成式 AI 应用
- **REST API 与生态**：HTTP JSON API 为主接口，官方与社区客户端覆盖 Java、Python、Go、Node.js 等主流语言
- **可观测与扩展**：与 Kibana、Beats、Elastic Agent 等组成 Elastic Stack；部分高级能力需订阅或 Elastic Cloud

## 对用户价值

Elasticsearch 把「搜索」从单一功能扩展为可观测性与数据检索的统一底座：既能做站内搜索、电商筛选与知识库检索，也能作为 ELK 栈核心承载日志分析与告警。REST 接口简单、水平扩展成熟，与 Kibana 可视化、Logstash/Beats 采集链路配合紧密。对团队而言，它是自建日志平台、全文检索与向量检索场景中最常被评估的基础设施之一，云托管（Elastic Cloud）与自管部署均有成熟路径。

## 与替代方案

- 相比 **OpenSearch**（Elasticsearch 分支），Elasticsearch 由 Elastic 主导演进，Search Labs 与 Kibana 等配套更新更快；OpenSearch 在 AWS 生态与 Apache 2.0 许可下强调开放治理，适合对云厂商绑定与许可有明确偏好的团队。
- 相比 **Solr**，Elasticsearch 在 REST API、分布式运维与实时索引方面更现代；Solr 在纯 Lucene 定制与部分传统企业搜索场景仍有存量用户。
- 相比 **Meilisearch / Typesense**，Elasticsearch 面向 PB 级集群、复杂聚合与可观测性全栈；轻量站内搜索若只需毫秒级 typo 容忍与小规模部署，专用轻量引擎上手更快。
- 相比 **ClickHouse / 专用 OLAP**，Elasticsearch 擅长检索、日志与时间序列聚合；大规模纯分析报表与 SQL 复杂 JOIN 仍更偏向列式数据库或数据仓库。
- 相比 **Redis / 专用向量库**，Elasticsearch 向量检索适合与现有日志、全文数据同集群复用；极低延迟、纯向量专库场景专用引擎仍具优势。

## 适应人群

- 需要全文搜索、日志分析或指标聚合的后端开发者与平台工程师。
- 负责 ELK/Elastic Stack 部署、容量规划与高可用的 SRE 与运维团队。
- 评估 RAG、语义检索或可观测性数据层架构的技术负责人与数据平台团队。

## 如何使用

### 前置条件

- 本地快速体验需安装 [Docker Desktop](https://www.docker.com/products/docker-desktop)；Windows 用户建议启用 WSL。
- 生产自管需规划 JVM 堆内存、磁盘 I/O、分片数量与集群节点角色；详见 [官方 sizing 指南](https://www.elastic.co/guide/en/elasticsearch/reference/current/size-your-shards.html)。
- 注意 **Elastic License 2.0 / SSPL** 许可边界：部分功能（如高级 ML、部分安全能力）需订阅；商业再分发与托管前请阅读 [Elastic 订阅说明](https://www.elastic.co/subscriptions)。

### 安装方式

**本地开发（官方 `start-local` 脚本，含 Elasticsearch + Kibana）**

```bash
curl -fsSL https://elastic.co/start-local | sh
```

脚本会在当前目录创建 `elastic-start-local` 文件夹，并通过 Docker 启动服务。此方式**仅用于本地开发与测试**，勿用于生产。

**生产环境**

- 托管部署： [Elasticsearch Service on Elastic Cloud](https://www.elastic.co/cloud/as-a-service)
- 自管安装：从 [elastic.co/downloads/elasticsearch](https://www.elastic.co/downloads/elasticsearch) 下载对应平台包，按 [安装文档](https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html) 配置

### 首次运行

`start-local` 完成后，默认端点：

- Elasticsearch：`http://localhost:9200`
- Kibana：`http://localhost:5601`

脚本会生成 `elastic` 用户随机密码并写入 `elastic-start-local/.env`，同时生成 API Key。进入目录加载环境变量：

```bash
cd elastic-start-local
source .env
export ES_LOCAL_PASSWORD
```

创建索引示例（Basic Auth）：

```bash
curl -u "elastic:${ES_LOCAL_PASSWORD}" \
  -X PUT "http://localhost:9200/my-new-index" \
  -H "Content-Type: application/json"
```

### 验证是否成功

**使用 API Key（推荐，脚本已写入 `.env`）**

```bash
source .env
curl "${ES_LOCAL_URL}" -H "Authorization: ApiKey ${ES_LOCAL_API_KEY}"
```

**使用用户名密码**

```bash
curl -u "elastic:${ES_LOCAL_PASSWORD}" http://localhost:9200
```

期望返回包含 `cluster_name` 与 `version` 的 JSON 集群信息。在 Kibana 中打开 **Management → Dev Tools**，执行 `GET /` 亦可验证。

### 常见坑 / 注意事项

- **`start-local` 非生产配置**：HTTPS 关闭、Basic 认证、仅绑定 localhost；生产需 TLS、角色权限与网络隔离。
- **试用许可**：`start-local` 含一个月全功能试用，之后回退为 Free and open - Basic；高级功能需对照订阅矩阵。
- **JVM 与分片**：默认堆大小与分片规划不当会导致 GC 压力与集群红态；升级或大索引导入前阅读 [Release Notes](https://github.com/elastic/elasticsearch/releases)。
- **版本兼容性**：Elasticsearch、Kibana、Beats 主版本需对齐；跨大版本升级需按官方迁移指南执行 reindex 或快照恢复。
- **许可与分支**：7.11 起源码采用 Elastic License 2.0 + SSPL 双许可；若需 Apache 2.0 兼容分支，可评估 OpenSearch，但 API 与生态已逐步分化。

---

# Redis

> 面向实时应用的内存数据结构存储，集缓存、消息队列、全文与向量检索于一体。

- 页面：https://www.niceshare.site/github/redis/
- 仓库：https://github.com/redis/redis
- 官网：https://redis.io
- 语言：C
- Stars：74995
- 许可证：RSALv2 / SSPL
- 标签：开发工具、缓存、系统工具
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Redis 是全球使用最广泛的内存数据结构服务器之一，主打亚毫秒级读写延迟，适合缓存、会话、队列、实时分析与 AI 向量检索等场景。自 v8.0 起，原 Redis Community Edition 更名为 **Redis Open Source**；本仓库为官方源码，生产环境通常优先使用 Docker 镜像、Homebrew、Snap 等二进制分发或 [Redis Cloud](https://cloud.redis.io/)，而非自行编译。Redis Ltd. 另提供 Redis Software 与 Redis Cloud 等企业/托管产品线。

## 核心特性

- **高性能内存引擎**：数据主要驻留内存，读写延迟极低，适合实时响应型应用
- **丰富数据结构**：String、Hash、List、Set、Sorted Set、JSON、Stream、Time Series 等，并支持事务与 Lua 脚本
- **检索与 AI 能力**：Redis Search 支持全文、地理空间与向量检索；Vector Set 可用于 RAG、语义缓存等 GenAI 场景
- **消息与事件**：Pub/Sub、Stream 与消费者组，可充当轻量消息中间件与事件存储
- **可扩展模块**：Modules API 可扩展命令与能力；从源码完整构建需 `BUILD_WITH_MODULES=yes` 以启用 Bloom Filter 等模块特性

## 对用户价值

Redis 把「极快缓存」与「多用途数据层」合二为一：既能减轻主库压力、加速 API，也能承载 Session、排行榜、限流、任务队列与实时推荐。协议简单、客户端生态覆盖 Python、Node.js、Go、Java、.NET 等主流语言，几乎每种后端栈都有成熟集成方案。对团队而言，它是 MySQL/PostgreSQL 之外最常见的基础设施组件之一，也是云托管与 K8s 部署的常规选项。

## 与替代方案

- 相比 **Memcached**，Redis 不仅做纯 KV 缓存，还提供持久化、复杂数据结构与 Pub/Sub，功能面更广；Memcached 在极简纯缓存场景仍足够轻量。
- 相比 **KeyDB / Valkey**（Redis 分支），Redis Open Source 由 Redis Ltd. 主导演进，Search、JSON、向量等能力集成更完整；Valkey 在 Linux 基金会生态下强调开源治理与兼容性，适合对许可与治理有明确偏好的团队。
- 相比 **RabbitMQ / Kafka**，Redis Stream 与 Pub/Sub 适合轻量队列与实时通知；高吞吐、长期日志留存与复杂消费语义仍更偏向专用消息系统。
- 相比 **Elasticsearch / 专用向量库**，Redis Search 适合与现有 Redis 集群复用、低延迟混合检索；超大规模全文或向量专库场景专用引擎仍具优势。

## 适应人群

- 需要缓存、Session 或分布式锁的后端开发者与全栈工程师。
- 负责中间件选型、容量规划与高可用的架构师与 SRE/运维工程师。
- 在 RAG、语义缓存、实时推荐等场景中评估内存数据层的 AI 应用开发者。

## 如何使用

### 前置条件

- 日常开发推荐 Docker、Homebrew 或 [官方二进制分发](https://redis.io/docs/latest/develop/get-started/)，生产环境需规划持久化、内存上限、网络 ACL 与备份策略。
- 从源码完整构建需 GCC、make、OpenSSL、CMake（≤ 3.31.6）等依赖；启用全部数据结构与模块时需设置 `BUILD_WITH_MODULES=yes` 等环境变量（详见 README）。
- 注意 **RSALv2 / SSPL** 许可边界：商业托管与再分发前请阅读 [官方许可说明](https://redis.io/legal/licenses/)。

### 安装方式

**Docker（最快上手）**

```bash
docker run -d -p 6379:6379 --name redis redis:latest
```

**macOS（Homebrew）**

```bash
brew tap redis/redis
brew install redis
brew services start redis
```

**从本仓库源码构建（开发/定制，含模块）**

```bash
git clone https://github.com/redis/redis.git
cd redis
export BUILD_TLS=yes BUILD_WITH_MODULES=yes INSTALL_RUST_TOOLCHAIN=yes
make -j "$(sysctl -n hw.ncpu 2>/dev/null || nproc)" all
```

### 首次运行

Docker 或包管理器安装后，默认监听 `6379`。使用 `redis-cli` 连接：

```bash
redis-cli ping
redis-cli set foo bar
redis-cli get foo
```

从源码构建时，在仓库根目录启动：

```bash
./src/redis-server redis-full.conf
```

另开终端执行 `./src/redis-cli` 进行交互。

### 验证是否成功

```bash
redis-cli ping
# 期望返回 PONG

redis-cli set mykey hello
redis-cli get mykey
# 期望返回 "hello"

redis-cli incr counter
redis-cli incr counter
redis-cli get counter
# 期望返回 "2"
```

应用侧可用对应语言客户端（如 [redis-py](https://redis.io/docs/latest/develop/clients/redis-py/)、[node-redis](https://redis.io/docs/latest/develop/clients/nodejs/)）执行相同读写测试。

### 常见坑 / 注意事项

- **内存与持久化**：默认全内存，需配置 `maxmemory` 与淘汰策略；RDB/AOF 持久化会影响性能与磁盘占用，生产环境应显式规划。
- **安全暴露**：勿将无认证实例暴露公网；设置 `requirepass` 或 ACL，并限制 bind 地址与防火墙规则。
- **完整模块构建**：Bloom Filter、Redis Search 等带 `*` 标记的特性需 `BUILD_WITH_MODULES=yes`；Ubuntu 26.04 等较新系统对 CMake/clang 版本有额外约束，见 README 对应章节。
- **开源 vs 商业**：Redis Open Source 与 Redis Software/Cloud 功能与 SLA 不同；企业合规、多活与托管需求请对照 [官方对比文档](https://redis.io/technology/advantages/)。
- **版本升级**：大版本升级前阅读 [Release Notes](https://github.com/redis/redis/releases)，关注命令行为变更与模块兼容性。

---

# Pi

> 极简可扩展的终端编码 Agent harness，多模型统一接入，用扩展与包适配你的工作流。

- 页面：https://www.niceshare.site/github/pi/
- 仓库：https://github.com/earendil-works/pi
- 官网：https://pi.dev
- 语言：TypeScript
- Stars：74464
- 许可证：MIT
- 标签：AI 编程、Agent、CLI
- 收录：2026-07-21（更新于 2026-07-21）

## 项目介绍

Pi 是 earendil-works 出品的极简终端编码 Agent harness：核心保持精简，通过 TypeScript 扩展、Skills、提示词模板、主题与 Pi Packages 适配你的工作流，而不是反过来改工作流迁就工具。仓库同时提供统一多厂商 LLM API（`pi-ai`）、Agent 运行时（`pi-agent-core`）、交互式 CLI（`pi-coding-agent`）与终端 UI 库（`pi-tui`），支持交互 / Print·JSON / RPC / SDK 四种运行形态。

## 核心特性

- **自扩展 harness**：用扩展、Skills、提示词模板、主题定制能力；可打包为 Pi Package，经 npm 或 git 安装分享
- **15+ 模型提供商**：Anthropic、OpenAI、Google、Bedrock、OpenRouter、Ollama、Kimi For Coding 等；会话中 `/model` 或 `Ctrl+L` 切换
- **树状可分享会话**：会话存为树；`/tree` 回到任意节点继续，`/export` 导出 HTML，`/share` 上传 gist 分享
- **四种运行模式**：交互式 TUI、`pi -p` Print/JSON、stdin/stdout RPC，以及可嵌入应用的 SDK（如 OpenClaw 集成）
- **刻意不做的能力**：默认无子 Agent、Plan 模式、权限弹窗、内置 MCP / TODO / 后台 bash——需要时自己扩展或装第三方包

## 对用户价值

把「读改代码 + 跑命令」收进一条可定制的终端工作流，同时保留上下文工程空间：`AGENTS.md` / `SYSTEM.md`、可定制 compaction、按需加载 Skills。若你讨厌密封式 Agent 产品，希望改 harness 而不是 fork 内核，Pi 的定位更接近可组合原语。MIT 许可，也便于团队评估二次集成与供应链加固实践（如 `--ignore-scripts` 安装、shrinkwrap）。

## 与替代方案

- 相比 **Claude Code / Codex**：Pi 模型无关、开源可扩展；前者深度绑定各自厂商订阅与产品体验。
- 相比 **OpenCode**：OpenCode 更强调开箱即用的多入口与 Plan/Build；Pi 更偏「最小核心 + 自己拼能力」，默认不做 Plan / 子 Agent / MCP。
- 相比 **Aider**：Aider 更轻、偏 Git diff 结对；Pi 提供完整 TUI、树状会话与 SDK/RPC 嵌入路径。
- **边界**：无内置权限系统，默认与启动用户同权；需要隔离请用 Docker / Gondolin / OpenShell 等容器化方案。聊天自动化另见 [pi-chat](https://github.com/earendil-works/pi-chat)。

## 适应人群

- 习惯终端，想用自然语言驱动改代码、跑命令，并自己扩展工具链的开发者。
- 需要把 Agent 以 SDK / RPC 嵌入自有产品或自动化流水线的工程团队。
- 想评估「可自改 harness」路线、对比密封式商业 Agent 的技术决策者。

## 如何使用

### 前置条件

- Node.js 与可用终端（Windows / Termux 等见官方平台文档）。
- 至少一个模型来源：订阅（Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot 等）走 `/login`，或配置对应 API Key。
- 理解安全边界：Pi 默认不限制文件系统 / 进程 / 网络权限。

### 安装方式

**npm（推荐加 `--ignore-scripts`）：**

```bash
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
```

**安装脚本（Linux / macOS）：**

```bash
curl -fsSL https://pi.dev/install.sh | sh
```

卸载（npm 安装）：

```bash
npm uninstall -g @earendil-works/pi-coding-agent
```

从源码开发本 monorepo 时，用仓库根目录的 `npm install --ignore-scripts` 与 `npm run build`（见 README Development）。

### 首次运行

进入项目目录启动：

```bash
cd your-project
pi
```

用订阅登录：

```text
/login
```

或先导出 API Key 再启动，例如：

```bash
export ANTHROPIC_API_KEY=sk-ant-...
pi
```

默认工具为 `read` / `write` / `edit` / `bash`。可用 `/model` 选模型，用自然语言下任务；需要更多能力再装 Skills、扩展或 `pi install` 包。

### 验证是否成功

命令 `pi` 能进入 TUI，完成 `/login` 或 API Key 鉴权后，对当前仓库提一个小问题（如「总结目录结构」）并得到合理回复，即说明安装与模型通路正常。可用 `/session` 查看会话信息，`/hotkeys` 核对快捷键。

### 常见坑 / 注意事项

- **无内置权限弹窗**：Agent 可读写文件并执行 bash；敏感环境请容器化，参见官方 containerization 文档。
- **安装务必关注供应链**：官方推荐 `npm install --ignore-scripts`；依赖生命周期脚本默认关闭。
- **贡献流程特殊**：新贡献者的 issue / PR 默认自动关闭，维护者每日复查；贡献前先读 `CONTRIBUTING.md`。
- **「缺功能」多半是设计**：MCP、子 Agent、Plan 等需自行扩展或安装第三方 Pi Package，而不是期待内置开关。

---

# CPython

> Python 官方参考实现，提供解释器、标准库与 C 扩展接口，支撑全球 Python 生态的核心源码仓库。

- 页面：https://www.niceshare.site/github/cpython/
- 仓库：https://github.com/python/cpython
- 官网：https://www.python.org
- 语言：Python
- Stars：73323
- 许可证：PSF-2.0
- 标签：开发工具、后端、CLI
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

CPython 是 [Python Software Foundation](https://www.python.org/psf/) 维护的 Python **官方参考实现**，包含解释器（字节码虚拟机）、内置类型、标准库以及 C 扩展 API。它以「 batteries included 」著称，语法简洁、动态类型，在 Web 后端、数据科学、自动化脚本、AI/ML 与 DevOps 等领域拥有最广泛的生态。本仓库为 CPython **核心源码**；日常开发通常从 [python.org](https://www.python.org/) 安装发行版，文档与教程亦以官网为准。

## 核心特性

- **解释型动态语言**：交互式 REPL、动态类型与 duck typing，适合快速原型与脚本化任务
- **丰富标准库**：`json`、`asyncio`、`pathlib`、`sqlite3`、`http` 等模块覆盖常见场景，减少第三方依赖
- **成熟发布节奏**：遵循 PEP 流程；Stable 分支提供 bugfix 与安全更新，feature 版本按 PEP 826 等计划发布
- **C 扩展与 FFI**：`ctypes`、`cffi` 及 C API 支持高性能扩展与系统库集成
- **开放治理**：PSF 与核心开发团队透明运作，Discourse、Issue Tracker 与 [devguide](https://devguide.python.org/) 规范贡献路径

## 对用户价值

若你需要一门上手快、生态完整、适合数据处理与自动化的通用语言，Python 是最主流的选择之一。CPython 作为参考实现，保证 PyPI 上绝大多数包的兼容基准；LTS 式 bugfix 分支为企业提供可预期的升级窗口。对于全栈与数据团队，Python 在 Django/FastAPI、Pandas、PyTorch 等栈中降低集成成本；代价是 GIL 限制 CPU 密集多线程并行，此类场景需借助 `multiprocessing`、C 扩展或替代实现。

## 与替代方案

- 相比 **[PyPy](https://www.pypy.org/)**，CPython 生态兼容性与第三方 C 扩展支持最完整；PyPy 通过 JIT 在部分纯 Python 负载上更快，但部分 C 扩展兼容性仍需谨慎验证。
- 相比 **[Node.js](https://nodejs.org/)**，Python 在数据科学、机器学习、科学计算与运维脚本领域工具链更成熟；Node.js 在前端同构、实时 I/O 与 npm 生态规模上占优，适合 JavaScript 全栈团队。
- 相比 **Go / Rust / Java**，Python 开发效率与可读性更高、入门门槛更低，适合 I/O 密集与快速迭代；对极致性能、强静态类型或特定企业中间件生态有强需求时，系统语言或 JVM 栈可能更合适。
- 相比 **Jython / GraalPython** 等替代实现，CPython 是 PyPI 与 C 扩展的事实标准；JVM 集成或 GraalVM 多语言场景可选专用实现，但生态覆盖面较小。
- 边界说明：本仓库用于**贡献 CPython 核心**或从源码构建；应用开发安装官方发行版或版本管理器即可，无需 clone 本 repo。

## 适应人群

- 构建 Web API、数据管道、自动化脚本、CLI 工具或 AI/ML 应用的后端、数据与全栈工程师。
- 维护 PyPI 包、锁定 Python 版本线、评估标准库行为或参与 PEP 讨论的企业技术负责人。
- 希望深入解释器、GIL、字节码、C API 或参与 CPython 核心贡献的系统级开发者（需阅读 [devguide](https://devguide.python.org/)）。

## 如何使用

### 前置条件

- 操作系统：macOS、Windows 10+、或主流 Linux 发行版（完整支持列表见 [devguide 依赖说明](https://devguide.python.org/getting-started/setup-building/#build-dependencies)）。
- 生产环境建议选用 **Stable bugfix 分支**（如 3.12、3.13 等当前维护线）；`main` 分支为开发版，不适合生产。
- 从源码构建需安装 C 编译器及 zlib、openssl、libffi 等依赖，复杂度远高于安装官方二进制。

### 安装方式

**方式一：官网安装包（推荐大多数用户）**

从 [python.org/downloads](https://www.python.org/downloads/) 下载对应平台的安装包或嵌入式发行版。

**方式二：版本管理器（多版本切换）**

```bash
# pyenv（macOS / Linux）
curl https://pyenv.run | bash
pyenv install 3.13.0
pyenv global 3.13.0
```

```bash
# Homebrew（macOS）
brew install python@3.13
```

```bash
# uv（跨平台，速度快，可管理 Python 版本）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.13
```

更多安装选项见 [Python 下载页](https://www.python.org/downloads/) 与各平台包管理器索引。

**方式三：从源码构建（贡献者与高级用户）**

```bash
git clone https://github.com/python/cpython.git
cd cpython
./configure --enable-optimizations   # 可选：PGO 优化构建
make
make test
sudo make install                  # 多版本并存时用 make altinstall
```

Windows 构建见 [PCbuild/readme.txt](https://github.com/python/cpython/blob/main/PCbuild/readme.txt)；macOS Framework 构建见 [Mac/README.rst](https://github.com/python/cpython/blob/main/Mac/README.rst)。

### 首次运行

```bash
python3 --version
python3 -c "print('Hello, Python')"
```

创建 `hello.py` 并运行：

```python
# hello.py
import sys
print(f"Python {sys.version_info.major}.{sys.version_info.minor} on {sys.platform}")
```

```bash
python3 hello.py
```

### 验证是否成功

- `python3 --version` 输出预期版本号（生产环境应为 Stable bugfix 线，如 `3.13.x`）。
- `python3 -c "print('ok')"` 输出 `ok`，无动态链接或模块加载错误。
- `python3 -m pip --version` 可正常输出（若发行版包含 pip）。
- 查阅 [docs.python.org](https://docs.python.org/3/) 确认本地版本与在线文档一致。

### 常见坑 / 注意事项

- **python vs python3**：部分系统 `python` 仍指向 Python 2 或不存在；脚本与 CI 中建议显式使用 `python3` 或虚拟环境。
- **源码仓库 vs 日常使用**：clone 本 repo 不等于「安装 Python」；贡献者需遵循 [devguide](https://devguide.python.org/)，构建依赖多、耗时长。
- **GIL 与并发**：CPU 密集多线程无法线性加速，需用 `multiprocessing`、asyncio（I/O 密集）或 C 扩展；3.13+ 提供可选 nogil 实验构建。
- **虚拟环境**：项目依赖应隔离在 `venv` 或 `uv`/`poetry` 管理的环境中，避免污染系统 Python。
- **中国大陆网络**：PyPI 安装缓慢可配置镜像（如 [pypi.tuna.tsinghua.edu.cn](https://pypi.tuna.tsinghua.edu.cn/)）；Python 二进制亦可使用国内镜像站加速下载。
- **许可证**：CPython 以 [PSF License](https://docs.python.org/3/license.html) 分发，可用于专有项目；Python 商标使用须遵循 PSF 商标政策。

---

# Ponytail

> 给 AI 编程 Agent 注入「懒 senior」思维的规则集，少写多余代码、保留安全底线。

- 页面：https://www.niceshare.site/github/ponytail/
- 仓库：https://github.com/DietrichGebert/ponytail
- 官网：https://ponytail.dev
- 语言：JavaScript
- Stars：72676
- 许可证：MIT
- 标签：AI 编程、Agent、开发工具
- 收录：2026-07-03（更新于 2026-07-03）

## 项目介绍

Ponytail 是一套面向 AI 编程 Agent 的规则与技能插件，核心理念是「能少写就少写，但绝不牺牲安全」。它让 Agent 在动手前先走一条决策阶梯：先问是否需要、能否复用现有代码、标准库或平台原生能力是否够用，最后才写最少必要的实现。官方在真实 Claude Code 会话（FastAPI + React 仓库、12 项功能任务）中测得：相比无技能基线，平均减少约 54% 代码量、20% 成本、27% 耗时，同时保持 100% 安全合规。

## 核心特性

- **决策阶梯（Decision Ladder）**：按 YAGNI → 复用代码库 → 标准库 → 原生平台 → 已装依赖 → 一行搞定 → 最小实现 的顺序选方案
- **安全底线不可砍**：验证、错误处理、安全与无障碍要求始终保留，不因追求简洁而牺牲
- **多 Agent 适配**：支持 Claude Code、Codex、GitHub Copilot CLI、OpenCode、Gemini、Pi、Hermes、Cursor、Windsurf、Cline 等 16 种宿主
- **分级强度控制**：`lite` / `full` / `ultra` / `off` 四档，可用 `/ponytail` 命令或环境变量切换
- **审查与审计命令**：`/ponytail-review` 检查当前 diff，`/ponytail-audit` 扫描全仓库过度工程化

## 对用户价值

AI Agent 常把简单需求写成「装依赖 + 封装组件 + 讨论时区」——Ponytail 专治这种过度建设。例如日期选择器，无技能时 Agent 可能引入 flatpickr 并写包装层；有 Ponytail 则直接 `<input type="date">`。在真实基准测试中，过度建设场景（日期选择器、颜色选择器）代码量可从数百行降至二十余行，而本就精简的代码几乎不受影响。对团队而言，这意味着更少的维护负担、更低的 token 成本，以及更可预测的 diff 规模。

## 与替代方案

- 相比 **caveman**（简洁 prose 控制组），Ponytail 在 LOC、token、成本、耗时四项指标上均更优，且是唯一在所有指标上均优于无技能基线的方案。
- 相比裸写「YAGNI + one-liner」提示词，Ponytail 在减少代码的同时保持 100% 安全分；裸提示词在安全对抗测试中仅 95%。
- 相比 **Superpowers** 等通用 Agent 技能库，Ponytail 专注「少写必要代码」这一单一命题，不提供测试驱动、规划等广谱能力。
- 若你更需要功能完备性与快速原型而非精简 diff，Ponytail 的 `ultra` 模式或关闭技能可能更合适。

## 适应人群

- 使用 Claude Code、Codex、Cursor 等 Agent 编码、但常被过度封装和多余依赖拖累的开发者。
- 希望降低 AI 生成代码维护成本、控制 token 开销的个人或小团队。
- 需要在多个 Agent 宿主间共享同一套「懒 senior」编码规范的工程团队。

## 如何使用

### 前置条件

- 已安装并配置好目标 Agent 宿主（如 Claude Code、Codex、OpenCode 等）。
- Claude Code / Codex 插件依赖 Node.js 生命周期钩子，需确保 `node` 在非交互式 shell 的 PATH 中（Nix/nvm 用户注意）。
- 无需配置文件即可使用；可选 `~/.config/ponytail/config.json` 或 `PONYTAIL_DEFAULT_MODE` 环境变量设置默认强度。

### 安装方式

**Claude Code（推荐，分两条命令执行）：**

```
/plugin marketplace add DietrichGebert/ponytail
```

```
/plugin install ponytail@ponytail
```

**Codex：**

```bash
codex plugin marketplace add DietrichGebert/ponytail
codex
```

在 `/plugins` 中选择 Ponytail 市场并安装，再在 `/hooks` 中信任其两个生命周期钩子。

**OpenCode（`opencode.json`）：**

```json
{ "plugin": ["@dietrichgebert/ponytail"] }
```

**Cursor / Windsurf / Cline / Copilot（编辑器）**：从仓库复制对应规则文件（`.cursor/rules/`、`.windsurf/rules/`、`.clinerules/`、`.github/copilot-instructions.md`）到项目根目录。

**Gemini CLI：**

```bash
gemini extensions install https://github.com/DietrichGebert/ponytail
```

### 首次运行

安装完成后，新会话默认以 `full` 模式激活。可用 `/ponytail lite` 或 `/ponytail ultra` 调整强度；`/ponytail off` 临时关闭。向 Agent 提出一个常见 UI 需求（如日期选择器），观察是否优先选用原生方案而非引入新依赖。

### 验证是否成功

- 执行 `/ponytail`（无参数）应返回当前模式。
- 执行 `/ponytail-review` 可对当前 diff 输出过度工程化检查清单。
- 执行 `/ponytail-gain` 可查看官方基准测试得分板。
- 若安装 Claude Code 插件后每轮无规则注入，检查 `node` 是否在 PATH 中。

### 常见坑 / 注意事项

- Claude Code 桌面版无 `/plugin` 命令，需通过 UI：Customize → + → Create plugin and add marketplace → Add from repository。
- Codex / Claude Code 的 marketplace 与 install 必须分两次 prompt 执行，合并为一条会失败。
- 卸载插件后可能残留 `~/.config/ponytail/config.json` 与 Claude `statusLine` 配置；可先运行 `node scripts/uninstall.js` 再执行宿主卸载命令。
- 指令-only 适配器（Cursor、Windsurf 等）加载始终开启的规则集，但不提供 `/ponytail` 等命令；需技能宿主才能使用完整命令集。

---

# protobuf

> Google 出品的跨语言结构化数据序列化方案，含 protoc 编译器与多语言运行时。

- 页面：https://www.niceshare.site/github/protobuf/
- 仓库：https://github.com/protocolbuffers/protobuf
- 官网：https://protobuf.dev
- 语言：C++
- Stars：71297
- 许可证：BSD-3-Clause
- 标签：开发工具、CLI、自动化
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Protocol Buffers（protobuf）是 Google 开源的语言中立、平台中立结构化数据序列化机制。开发者用 `.proto` 文件描述消息与 RPC 服务，再通过 `protoc` 编译器生成 C++、Java、Python、Go 等语言的类型安全代码。其二进制格式紧凑、解析速度快，是 gRPC 的默认载荷格式，也广泛用于微服务接口契约、配置与持久化存储。

## 核心特性

- **Schema 驱动**：以 `.proto` 定义消息字段、枚举与服务，编译期生成强类型 API，减少手写序列化代码
- **跨语言生态**：官方维护 C++、Java、Python、C#、Ruby、PHP、Objective-C 等运行时，Go/JavaScript 等由姊妹仓库提供
- **高效二进制编码**：相较 XML/JSON 体积更小、解析更快，适合高吞吐 RPC 与移动端场景
- **可演进的数据模型**：通过字段编号与 `optional`/`repeated` 等规则支持向后兼容的 schema 演进
- **工具链成熟**：`protoc` 预编译包、Bazel 模块（Bzlmod/WORKSPACE）集成，以及 [protobuf.dev](https://protobuf.dev) 完整文档与教程

## 对用户价值

protobuf 把「数据结构定义」提升为团队可共享的契约：一份 `.proto` 可在多语言服务间复用，避免各端各自维护 JSON 结构导致的不一致。代码生成降低样板代码与运行时错误，配合 gRPC 可快速搭建类型安全的 RPC 栈。对需要高性能序列化、明确版本演进策略的后端与基础设施团队，它是事实上的行业标准之一。

## 与替代方案

- 相比 **JSON**，protobuf 二进制更小、解析更快，且 schema 在编译期校验；JSON 更易人工阅读与调试，适合对外 REST API 或日志，二者常并存（如 gRPC 对内、JSON 对外）。
- 相比 **Apache Avro**，两者都强调 schema 与演进；Avro 在 Hadoop/Kafka 大数据生态更常见，protobuf 在 gRPC、移动端与 Google 系工具链中渗透更深。
- 相比 **Cap'n Proto / FlatBuffers**，后者偏向零拷贝、低延迟读取；protobuf 生态与语言支持更广，工具链与社区体量更大，选型需权衡延迟敏感性与集成成本。
- 相比 **MessagePack**，MessagePack 更轻量但缺少 `.proto` 级别的跨语言契约与 `protoc` 代码生成体系。

## 适应人群

- 使用 gRPC 或需要跨语言 RPC/消息契约的后端与平台工程师。
- 维护多语言微服务、希望统一数据模型并自动生成客户端/服务端代码的团队。
- 在 CI/CD 中集成 `protoc` 代码生成、管理 `.proto` 版本与兼容性的基础设施开发者。

## 如何使用

### 前置条件

- 明确目标语言（C++、Java、Python 等）与对应的 protobuf 运行时包。
- 非 C++ 用户通常只需预编译的 `protoc` 二进制；C++ 或需改源码时，需 Bazel/g++ 或 CMake 等构建环境（见 [C++ 安装说明](https://github.com/protocolbuffers/protobuf/blob/main/src/README.md)）。
- 生产环境建议锁定 [Releases](https://github.com/protocolbuffers/protobuf/releases) 版本，避免直接跟踪 `main` 分支带来的不兼容变更。

### 安装方式

**安装 protoc 编译器（推荐：预编译包）**

从 [GitHub Releases](https://github.com/protocolbuffers/protobuf/releases) 下载对应平台的 `protoc-$VERSION-$PLATFORM.zip`，解压后将 `bin/protoc` 加入 `PATH`。旧版本也可在 [Maven 仓库](https://repo1.maven.org/maven2/com/google/protobuf/protoc/) 查找。

**Python 运行时（多数用户）**

```bash
pip install protobuf
```

**从源码构建 protoc（C++ / 需定制时）**

```bash
git clone https://github.com/protocolbuffers/protobuf.git
cd protobuf
git submodule update --init --recursive
bazel build :protoc :protobuf
# Linux 示例：cp bazel-bin/protoc /usr/local/bin
```

各语言运行时安装路径见仓库 README 中的 [语言目录表](https://github.com/protocolbuffers/protobuf#protobuf-runtime-installation)。

### 首次运行

1. 编写 `person.proto` 等 schema 文件（可参考 [官方教程](https://protobuf.dev/getting-started)）。
2. 用 `protoc` 生成目标语言代码，例如 Python：`protoc --python_out=. person.proto`。
3. 在应用中 import 生成模块并序列化/反序列化消息；gRPC 用户需额外使用对应语言的 gRPC 插件生成 stub。

仓库 `examples/` 目录提供多语言示例，[protobuf.dev 入门指南](https://protobuf.dev/getting-started) 是最佳学习路径。

### 验证是否成功

- 执行 `protoc --version` 应输出版本号。
- Python：`python -c "import google.protobuf; print(google.protobuf.__version__)"` 无报错。
- 对示例 `.proto` 运行 `protoc` 生成代码后，能完成一次 `SerializeToString` / `ParseFromString`（或等价 API）即表示工具链可用。

### 常见坑 / 注意事项

- **版本对齐**：`protoc` 主版本应与各语言 `protobuf` 运行时包匹配；混用易导致生成代码与库不兼容。
- **勿跟踪 main**：README 明确警告从 `main` 构建可能遭遇破坏性变更；生产与库依赖应 pin 到 release 分支上的 tag。
- **Python 实现后端**：可通过环境变量 `PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION` 选择 `upb`/`cpp`/`python`；默认自动选择，性能差异见 [python/README](https://github.com/protocolbuffers/protobuf/blob/main/python/README.md)。
- **Bazel 集成**：Bazel 8+ 推荐 Bzlmod（`bazel_dep(name = "protobuf", version = ...)`）；旧 WORKSPACE 流程在 30.x 后需额外加载 `rules_java` / `rules_python`。
- **许可证**：源码采用 BSD-3-Clause；商业使用前请阅读仓库 LICENSE 与 [版本支持策略](https://protobuf.dev/version-support/)。

---

# Agent Skills

> Addy Osmani 出品的生产级 Agent 工程技能包，24 项工作流与 8 个斜杠命令覆盖从需求到上线全周期。

- 页面：https://www.niceshare.site/github/agent-skills/
- 仓库：https://github.com/addyosmani/agent-skills
- 语言：Shell
- Stars：70464
- 许可证：MIT
- 标签：AI 编程、Agent、工作流
- 收录：2026-07-06（更新于 2026-07-06）

## 项目介绍

Agent Skills 是 Addy Osmani 维护的一套 **面向 AI 编码代理的生产级工程技能库**。它将资深工程师在真实项目中使用的规格、任务拆分、增量实现、测试、审查与上线流程，封装成 24 个结构化 `SKILL.md` 工作流，并配套 8 个斜杠命令（`/spec`、`/plan`、`/build` 等）映射完整研发生命周期。技能会在相关场景自动触发，也可被直接引用，帮助 Agent 在「最短路径」之外仍保持可验证的工程纪律。

## 核心特性

- **全生命周期覆盖**：Define → Plan → Build → Verify → Review → Ship 六阶段，含 `spec-driven-development`、`test-driven-development`、`code-review-and-quality` 等 24 项技能
- **8 个斜杠命令**：`/spec`、`/plan`、`/build`、`/test`、`/review`、`/webperf`、`/code-simplify`、`/ship`；`/build auto` 可在一次批准后自主跑完计划内任务
- **反合理化设计**：每项技能含常见借口与反驳表、验证门禁与退出标准，「看起来对」不算完成
- **4 个专业 Agent 人设**：代码审查、测试工程、安全审计、Web 性能审计，可按场景组合编排
- **多宿主安装路径**：官方推荐 Claude Code 插件市场；同时提供 Cursor、Gemini CLI、Antigravity、Windsurf、OpenCode、Copilot、Kiro 等接入文档
- **融入 Google 工程实践**：API 设计中的 Hyrum's Law、测试金字塔与 Beyoncé Rule、~100 行变更规范、Trunk-based 开发、Shift Left 与 Feature Flag 等原则嵌入步骤

## 对用户价值

AI 编码助手默认倾向跳过规格、测试与安全审查，产出「能跑但难维护」的代码。Agent Skills 把生产级工程判断编码成可重复执行的工作流：何时写 PRD、如何拆任务、怎样增量提交、合并前过哪些质量门禁。对个人开发者，它减少返工与范围漂移；对团队，它提供可版本化、可跨工具复用的 Agent 行为标准，让结对编程更接近资深工程师的做事方式。

## 与替代方案

- 相比 [Superpowers](https://github.com/obra/superpowers)，本仓库更强调 **Google 风格工程实践与全栈质量门禁**（安全、性能、可观测性、废弃迁移等），并内置 `/webperf` 等专项命令；官方 [comparison.md](https://github.com/addyosmani/agent-skills/blob/main/docs/comparison.md) 提供与 Superpowers、Matt Pocock skills 的并排对比。
- 相比 [Anthropic Agent Skills](https://github.com/anthropics/skills) 官方规范与示例库，这里侧重 **端到端软件交付流程** 而非文档处理或跨平台技能标准本身；二者可组合——用 agentskills.io 格式分发，用本仓库补齐研发方法论。
- 相比单文件 [Karpathy Coding Guidelines](https://github.com/multica-ai/andrej-karpathy-skills) 行为准则，本仓库提供 **分阶段可触发的完整工作流与子 Agent 人设**，而非仅约束编码风格与改动范围。
- 相比项目级 Cursor Rules，Skills 支持 **按任务渐进加载**、反合理化表与明确验证证据，token 开销更可控。

## 适应人群

- 使用 Claude Code、Cursor 或 Gemini CLI，希望 Agent 按规格驱动开发与 TDD 推进功能的开发者。
- 需要在合并前强制代码审查、安全与性能门禁的 Tech Lead 或 Staff 工程师。
- 已熟悉基础 Agent 用法，想引入 Google 工程文化式流程编排、减少「直接开写」反模式的效率型用户。

## 如何使用

### 前置条件

- 使用 README 列出的某一 Agent 宿主；Claude Code 为官方推荐路径。
- 对目标项目有 Git 读写权限；`/build`、`/ship` 等流程假设可运行测试与提交。
- 接受流程偏向规格先行与测试证明——简单一行修改可能被工作流「包装」，需结合任务复杂度判断。

### 安装方式

**Claude Code（推荐）**

```
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills
```

若 marketplace 克隆报 SSH 错误，可改用 HTTPS：

```
/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills
```

本地开发调试：

```bash
git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills
```

**Cursor**

将单个 `SKILL.md` 复制到 `.cursor/rules/`，或引用整个 `skills/` 目录；详见仓库 [docs/cursor-setup.md](https://github.com/addyosmani/agent-skills/blob/main/docs/cursor-setup.md)。

**Gemini CLI**

```bash
gemini skills install https://github.com/addyosmani/agent-skills.git --path skills
```

**Antigravity CLI**

```bash
agy plugin install https://github.com/addyosmani/agent-skills.git
```

更多宿主（Windsurf、OpenCode、Copilot、Kiro 等）见 [docs/getting-started.md](https://github.com/addyosmani/agent-skills/blob/main/docs/getting-started.md)。

### 首次运行

安装后新开 Agent 会话，对一个中等复杂度功能尝试 `/spec` 或描述新需求。Agent 应触发 `spec-driven-development` 或 `interview-me` 等技能，在写代码前产出 PRD 或澄清问题，而非立即修改文件。

### 验证是否成功

确认斜杠命令可用（Claude Code 插件列表中出现 `addy-agent-skills`）；发起功能请求后 Agent 引用具体 skill 名称并按步骤执行。运行 `/test` 时应看到测试驱动与证据要求，而非仅凭主观判断宣布完成。

### 常见坑 / 注意事项

- Claude Code marketplace 默认通过 SSH 克隆；无 GitHub SSH 密钥时需改用 HTTPS marketplace URL（见上文）。
- `/build auto` 减少任务间人工 stepping，但**不跳过验证**——失败或高风险步骤仍会暂停，勿误以为完全无人值守。
- 与 Superpowers 等工作流库存在理念重叠，选型前建议阅读 [docs/comparison.md](https://github.com/addyosmani/agent-skills/blob/main/docs/comparison.md)。
- Skills 为纯 Markdown，行为取决于宿主实现与模型版本；关键任务请在自有环境回归验证。
- MIT 许可，可自由用于个人项目与团队工具链集成。

---

# anime.js

> 轻量级 JavaScript 动画库，支持 CSS/SVG/DOM 与对象属性，API 简洁、场景覆盖广。

- 页面：https://www.niceshare.site/github/anime/
- 仓库：https://github.com/juliangarnier/anime
- 官网：https://animejs.com
- 语言：JavaScript
- Stars：70294
- 许可证：MIT
- 标签：开发工具、前端、可视化
- 收录：2026-06-24（更新于 2026-06-24）

## 项目介绍

anime.js 是由 Julian Garnier 维护的 JavaScript 动画引擎，当前主版本为 V4，定位为快速、多用途且轻量的动画库。它可用简洁 API 驱动 CSS 属性、SVG、DOM 属性以及普通 JavaScript 对象，适合在网页中实现微交互、序列动画与复杂时间轴编排。官方文档与示例集中在 [animejs.com](https://animejs.com)；日常开发通过 npm 安装 `animejs` 并以 ES Module 引入即可。

## 核心特性

- **统一动画 API**：`animate()` 可对选择器、DOM 节点或 JS 对象施加变换，支持 `duration`、`delay`、`ease`、`loop`、`alternate` 等常用参数
- **多目标类型**：覆盖 CSS 属性、SVG 路径与属性、DOM attribute，以及任意数值对象属性
- **时间轴与交错**：内置 `timeline` 模块编排多段动画；`stagger()` 为列表元素生成递进延迟，适合卡片、菜单等批量动效
- **丰富缓动与弹簧**：提供多种 easing（含 cubic-bezier、spring 等），并支持 WAAPI 等浏览器能力适配
- **模块化分包**：V4 按 `animation`、`timeline`、`timer` 等子路径导出，可按需 tree-shake，减小打包体积
- **TypeScript 支持**：发布包内含 `.d.ts` 类型声明，便于在 TS 项目中集成

## 对用户价值

手写 CSS `@keyframes` 或原生 Web Animations API 在复杂序列、对象插值与 SVG 路径动画上往往样板代码多、可读性差。anime.js 把「目标 + 属性 + 时间曲线」收敛成声明式配置，让前端与创意开发者能快速实现落地页动效、数据可视化过渡、SVG 图标动画等场景。MIT 许可、无运行时框架绑定，可与 React、Vue、Svelte 或纯原生页面配合；V3 用户可参照官方 [迁移指南](https://github.com/juliangarnier/anime/wiki/Migrating-from-v3-to-v4) 升级。

## 与替代方案

- 相比 [GSAP](https://gsap.com/)，anime.js 更轻量、API 更扁平，MIT 完全免费；GSAP 生态更成熟，ScrollTrigger、Morph 等高级能力更强，部分插件需商业许可，适合大型动效生产管线。
- 相比 [Motion](https://motion.dev/)（原 Framer Motion 核心），anime.js 不绑定 React，适合多框架或 vanilla JS 项目；Motion 在 React 组件级动画与布局过渡上集成更深。
- 相比纯 CSS Animation / Transition，anime.js 便于对象属性插值、SVG 路径与多段时间轴编排；简单 hover 或单次过渡仍可直接用 CSS，成本更低。
- 边界说明：npm 包名为 **`animejs`**（非 `anime`）；V4 与 V3 API 有破坏性变更，旧项目升级前务必阅读迁移文档。

## 适应人群

- 需要为落地页、产品演示或营销站点添加微交互与序列动画的前端工程师与创意开发者。
- 在 SVG 图标、数据图表或 Canvas/WebGL 场景中，希望用统一 API 驱动属性过渡的 UI 开发者。
- 评估轻量动画库（与 GSAP、CSS、Motion 对比）并关注 MIT 许可与包体积的技术负责人。

## 如何使用

### 前置条件

- 现代浏览器（支持 ES Modules；部分能力依赖 WAAPI 等浏览器 API）。
- Node.js 与 npm/pnpm/Yarn（用于打包集成）；或可直接通过 CDN 引入 UMD 包做原型验证。
- 基础 JavaScript 与 DOM/CSS 知识；从 V3 升级需对照官方迁移指南。

### 安装方式

**方式一：npm 安装（推荐）**

```bash
npm install animejs
```

**方式二：pnpm / Yarn**

```bash
pnpm add animejs
# 或
yarn add animejs
```

**方式三：CDN（UMD，适合快速原型）**

```html
<script src="https://cdn.jsdelivr.net/npm/animejs/dist/bundles/anime.umd.min.js"></script>
```

### 首次运行

在入口文件中按 V4 方式引入并执行一段基础动画：

```javascript
import { animate, stagger } from 'animejs';

animate('.square', {
  x: 320,
  rotate: { from: -180 },
  duration: 1250,
  delay: stagger(65, { from: 'center' }),
  ease: 'inOutQuint',
  loop: true,
  alternate: true,
});
```

确保页面存在 `.square` 元素，并在 bundler（Vite、Webpack 等）中正常解析 `animejs` 的 ES Module 导出。完整 API 见 [官方文档](https://animejs.com/documentation)。

### 验证是否成功

- 页面加载后目标元素应产生位移与旋转动画，且循环交替播放。
- 浏览器开发者工具 Network 面板应成功加载 `animejs` 模块或 UMD 脚本，Console 无模块解析错误。
- 若使用 TypeScript，IDE 应能识别 `animate`、`stagger` 等导出符号的类型提示。

### 常见坑 / 注意事项

- **包名**：npm 安装为 `animejs`，`import` 路径也是 `'animejs'`，勿与旧版 `anime` 包名混淆。
- **V3 → V4**：API 与模块结构有变更，旧代码不能直接替换 import；升级前阅读 [Migrating from v3 to v4](https://github.com/juliangarnier/anime/wiki/Migrating-from-v3-to-v4)。
- **SSR**：在 Next.js 等服务端渲染框架中，动画逻辑应放在客户端生命周期（`useEffect` 或 `'use client'`）内执行，避免 `window`/`document` 在服务端报错。
- **性能**：大量并发动画或复杂 SVG 路径时建议控制同时运行的实例数量，必要时结合 `requestAnimationFrame` 与 CSS `will-change` 优化。

---

# Cline

> 可在 IDE、CLI 与看板中运行的开源自主编码代理，强调可审查的文件级改动。

- 页面：https://www.niceshare.site/github/cline/
- 仓库：https://github.com/cline/cline
- 官网：https://cline.bot
- 语言：TypeScript
- Stars：63531
- 许可证：Apache-2.0
- 标签：AI 编程、Agent、CLI
- 收录：2026-06-19（更新于 2026-06-19）

## 项目介绍

Cline 是面向真实开发任务的开源自主编码代理，支持 VS Code 扩展、终端 CLI 与 Web Kanban 看板。它的重点不是只补全一段代码，而是让代理能读取项目、提出计划、编辑文件、运行命令，并在关键步骤请求用户确认。

## 核心特性

- **VS Code 扩展**：在编辑器内创建文件、运行终端、浏览网页并使用工具
- **CLI**：支持交互式对话或 headless 模式，便于 CI/CD 与脚本集成
- **Kanban**：Web 看板上并行运行多个代理，独立 worktree 与依赖链
- 文件级改动可审查，保留人工确认节奏
- 开源 SDK，便于研究代理产品形态

## 对用户价值

Cline 帮助开发者把跨文件、多步骤任务交给代理执行，同时保留检查和确认的节奏。对于希望理解「自主代理如何与本地开发环境协作」的用户，它也提供了相当直接的工程样本与可扩展接口。

## 与替代方案

- 相比 Aider 等终端结对工具，Cline 自主性更强，可执行终端与多文件编排。
- 相比 Cursor Agent 等商业产品，Cline 开源可审计，模型与部署更灵活。
- 若只需轻量补全而非代理任务，Continue 或 Copilot 可能更合适。

## 适应人群

- 经常处理跨文件修改的开发者。
- 想研究编码代理产品形态的工具作者。
- 希望在终端或 IDE 中尝试 agentic workflow 的团队。

## 如何使用

### 前置条件

- VS Code（扩展方式）或 Node.js 环境（CLI / Kanban）。
- 所用模型的 API 密钥（Claude、OpenAI 等）。
- 建议在可回滚的 Git 分支上试用。

### 安装方式

- **IDE**：在 VS Code 扩展市场搜索「Cline」安装。
- **CLI**：见 [官方文档](https://docs.cline.bot) 中的 CLI 安装说明。

### 首次运行

打开 Cline 面板或执行 CLI，配置模型后描述一个小任务（如补充测试或更新文档），观察代理的计划与文件变更请求。

### 验证是否成功

确认代理能读取项目文件、生成 diff，并在你批准后正确写入；终端命令应在沙箱策略允许范围内执行。

### 常见坑 / 注意事项

- 首次使用限制任务范围，避免大范围重构失控。
- 仔细审查代理请求的终端命令与网络访问。
- Kanban 并行任务会占用更多 API 配额与磁盘（多 worktree）。

---

# Warp

> 从终端演进的 Agent 开发环境，块编辑 UI、内置 Oz 与主流编码 Agent 集成。

- 页面：https://www.niceshare.site/github/warp/
- 仓库：https://github.com/warpdotdev/warp
- 官网：https://www.warp.dev
- 语言：Rust
- Stars：62063
- 许可证：AGPL-3.0
- 标签：CLI、开发工具、Agent
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Warp 是用 Rust 打造的现代终端与 Agent 开发环境，把块级输出、代码编辑与 AI 辅助整合进同一界面。它内置 SOTA Agent **Oz**，也可直接运行 Claude Code、Codex、Gemini CLI 等编码 Agent；**Oz 平台**则支持在云端并行调度可编程、可审计的编码 Agent，解决「传统终端跟不上开发方式、Agent 工具难以超出本机规模」的痛点。客户端以 AGPL-3.0 开源，服务端部分仍闭源。

## 核心特性

- **现代终端 UI**：块编辑、智能补全、Workflows 与主题扩展，支持 bash、fish、zsh、PowerShell
- **内置 Agent Oz**：终端内原生 AI 辅助，可理解会话上下文并代为执行或解释命令
- **编码 Agent 集成**：同一环境运行 Claude Code、Codex、Gemini CLI 等 CLI 编码工具
- **Oz 云端编排**：并行启动大量编码 Agent，可编程、可审计、可 steer，适合自动化重复任务
- **跨平台**：macOS、Windows、Linux 官方安装包，支持从源码构建 `warp-oss` 开发版
- **协作与扩展**：Drive、实时协作能力；社区主题与 [Workflows](https://github.com/warpdotdev/workflows) 仓库开放共享

## 对用户价值

传统终端把输出当纯文本流，AI 工具又往往散落在 IDE 插件与多个 CLI 之间。Warp 把「跑命令、看结果、改代码、调 Agent」收进一个原生终端体验：块 UI 让日志与 diff 可读性更高，内置与外部 Agent 减少窗口切换，Oz 则把 Agent 工作流从单机扩展到云端并行。对日常重度命令行 + AI 编程的用户，它是终端换代而非再叠一层插件。

## 与替代方案

- 相比 **iTerm2**，Warp 提供块编辑、AI 原生 UI 与 Agent 集成；iTerm2 开源可审计、tmux/Python 自动化更成熟，但无内置 Agent 与现代编辑体验。
- 相比 **Alacritty / Ghostty** 等 GPU 终端，Warp 功能更完整（补全、Agent、协作），体积与账户依赖更大；若只需极速纯终端，后者更轻。
- 相比 **VS Code / Cursor 内置终端**，Warp 是独立终端应用，Oz 与并行云端 Agent 面向「终端即 IDE」工作流；若已在 GUI IDE 内完成大部分编辑，迁移收益需评估。
- **Oz 云端 Agent** 与本地 CLI Agent 互补：需要大规模并行或脱离本机资源时再上 Oz；纯本地隐私场景可只用开源客户端与自带 Shell。

## 适应人群

- 希望把日常 SSH、构建、调试与 AI 辅助统一进现代终端的全栈与 DevOps 工程师。
- 已在用 Claude Code、Codex 等 CLI Agent，想要更好终端 UX 与上下文管理的开发者。
- 需要并行、可编排云端编码 Agent 的小团队或自动化重度用户（Oz 平台）。

## 如何使用

### 前置条件

- **macOS**、**Windows** 或 **Linux**（见 [官方下载页](https://www.warp.dev/download) 平台说明）
- 默认 Shell：bash、fish、zsh 或 PowerShell（pwsh）；其他 Shell 可能回退到 zsh
- 首次启动需联网；之后可离线使用基础终端，AI 与协作功能需网络
- 注册 Warp 账户为可选；使用 Oz 云端 Agent 需按官方策略登录与配置
- 从源码构建：macOS 需 Xcode、固定 Rust 工具链、`protoc` 等（见仓库 `CONTRIBUTING.md`）

### 安装方式

- **macOS（Homebrew，推荐）**：

```sh
brew install --cask warp
```

- **各平台安装包**：从 [warp.dev/download](https://www.warp.dev/download) 下载；尝鲜可用 [Preview 构建](https://www.warp.dev/download-preview)

- **从源码构建（AGPL 客户端）**：

```bash
git clone https://github.com/warpdotdev/warp.git
cd warp
./script/bootstrap
cargo run
```

`cargo run` 会启动本地 checkout 构建的 `warp-oss` 二进制；完整依赖与开发流程见仓库 `README.md` 与 `CONTRIBUTING.md`。

### 首次运行

安装后打开 Warp，可选注册账户或跳过。在 Settings > Features > Session 中确认默认 Shell；若从 iTerm2、VS Code 等迁移，可参考 [Migrate to Warp](https://docs.warp.dev/getting-started/migrate-to-warp) 导入设置。需要 AI 时在终端内唤起 Oz 或配置外部编码 Agent CLI。

### 验证是否成功

新建本地会话，运行简单命令（如 `echo`、`ls`）确认块输出与补全正常。若启用 Agent，发起一次小任务（解释命令或生成脚本）并查看响应。从源码构建时确认 `warp-oss` 窗口可启动且无阻塞性编译错误。

### 常见坑 / 注意事项

- GitHub 仓库同时用于 **Issue / 功能请求** 与 **开源客户端源码**；服务端与部分商业能力不在仓库内，部署前阅读 [开源讨论](https://github.com/warpdotdev/Warp/discussions/400) 与许可说明。
- 客户端为 **AGPL-3.0**，二次分发或修改网络服务相关代码需遵守 Copyleft；部分组件另含 MIT 许可。
- AI、Oz 与 Drive 涉及账户、计费与数据策略，生产环境使用前查阅 [官方文档](https://docs.warp.dev/) 隐私与登录故障排除页。
- 自编译门槛高于安装包；依赖平台原生工具链，CI 或无头环境构建需额外配置。

---

# Git

> 分布式版本控制系统，支撑代码协作、分支管理与开源生态的底层工具与官方源码仓库。

- 页面：https://www.niceshare.site/github/git/
- 仓库：https://github.com/git/git
- 官网：https://git-scm.com
- 语言：C
- Stars：61581
- 许可证：GPL-2.0
- 标签：开发工具、CLI、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Git 是由 Linus Torvalds 发起的**分布式版本控制系统（DVCS）**，以快照式对象存储、轻量分支与本地完整仓库著称，已成为现代软件协作的事实标准。它提供从日常 `commit`/`push`/`pull` 到 `rebase`、`cherry-pick`、子模块等高级操作，并暴露 plumbing 命令供工具链深度集成。本仓库为 Git **官方源码镜像**（GitHub 只读发布）；日常安装与文档以 [git-scm.com](https://git-scm.com/) 为准，补丁贡献通过邮件列表与 [GitGitGadget](https://gitgitgadget.github.io/) 流程进行。

## 核心特性

- **分布式架构**：每位开发者拥有完整历史副本，离线可提交、分支与合并，无需持续连接中央服务器
- **快照式对象模型**：内容寻址的 blob/tree/commit 与 SHA-1/SHA-256 对象库，支持高效增量存储与完整性校验
- **轻量分支与合并**：分支创建与切换成本极低，内置三路合并、冲突标记与多种合并策略
- **丰富命令分层**：porcelain 面向日常操作，plumbing 暴露底层对象与引用，便于 IDE、CI 与托管平台集成
- **开放治理与文档**：GPLv2 许可；[Pro Git](https://git-scm.com/book) 与 `git help` 提供完整命令参考，社区通过 `git@vger.kernel.org` 邮件列表演进

## 对用户价值

若你需要追踪代码变更、并行开发功能分支、审查合并或回滚发布，Git 几乎无可替代。分布式模型让个人与小团队可在本地快速迭代，大型组织则通过 GitHub、GitLab、Gitea 等托管层叠加 PR/MR、权限与 CI。相比集中式 VCS，Git 在分支实验、离线工作与 fork 协作上更灵活；代价是学习曲线（rebase vs merge、reflog、子模块等概念需时间消化），以及大仓库或二进制资产的存储与克隆成本需配合 LFS、稀疏检出等策略。

## 与替代方案

- 相比 **[Mercurial (hg)](https://www.mercurial-scm.org/)**，Git 生态规模、托管平台集成与招聘市场显著更大；Mercurial 命令模型相对线性，适合已深度绑定 hg 工作流的遗留团队，新项目极少再选。
- 相比 **[Subversion (SVN)](https://subversion.apache.org/)**，Git 的分布式与分支模型更适合并行特性开发与开源协作；SVN 目录级权限与集中式 checkout 在部分传统企业场景仍有存量，但新团队普遍转向 Git。
- 相比 **Perforce / Plastic SCM**，Git 对开源与互联网团队零许可成本、工具链免费；Perforce 等在大规模二进制与游戏/影视资产场景有专用优化，需按资产规模评估。
- 相比 **GitHub / GitLab 平台**，Git 是**本地版本控制引擎**，托管平台在其上提供远程仓库、Issue、CI 与权限；学 Git 不等于学 GitHub Flow，但二者在工程实践中通常一起使用。
- 边界说明：本仓库用于**阅读源码、从源码构建或向 Git 核心贡献**；应用开发者安装 [git-scm.com](https://git-scm.com/downloads) 或系统包管理器即可，无需 clone 本 repo。

## 适应人群

- 需要管理代码历史、功能分支、发布标签与 hotfix 流程的后端、前端、移动端与 DevOps 工程师。
- 制定团队分支策略（Git Flow、Trunk-Based、GitHub Flow）、Code Review 规范或评估托管平台选型的技术负责人。
- 希望深入 packfile、refspec、index、hooks 或参与 Git 核心开发的系统级开发者（需阅读 [Documentation/SubmittingPatches](https://github.com/git/git/blob/master/Documentation/SubmittingPatches)）。

## 如何使用

### 前置条件

- 操作系统：macOS、Windows 10+、或主流 Linux 发行版；Windows 可选 [Git for Windows](https://gitforwindows.org/)（含 Git Bash）。
- 生产协作建议 Git **2.40+**（支持现代默认分支名、`git switch`/`restore` 等）；过旧发行版可能缺少 SHA-256 过渡特性或安全补丁。
- 从本仓库源码构建需 C 编译器、curl、zlib、OpenSSL 等依赖（见仓库 `INSTALL` 与 `Makefile`），复杂度远高于安装二进制包。

### 安装方式

**方式一：官方安装包（推荐大多数用户）**

从 [git-scm.com/downloads](https://git-scm.com/downloads) 下载对应平台安装包。

**方式二：系统包管理器**

```bash
# macOS（Homebrew）
brew install git

# macOS 亦可安装 Xcode Command Line Tools（版本可能偏旧）
xcode-select --install

# Debian / Ubuntu
sudo apt update && sudo apt install git

# Fedora
sudo dnf install git
```

**方式三：Windows**

下载并运行 [Git for Windows](https://gitforwindows.org/) 安装程序，安装后在 Git Bash 或 PowerShell 中使用 `git`。

**方式四：从源码构建（贡献者与高级用户）**

```bash
git clone https://github.com/git/git.git
cd git
make configure
./configure --prefix=/usr/local
make all doc
sudo make install install-doc install-html
```

也可参考仓库根目录 `INSTALL` 中的 `profile` 构建以换取少量 CPU 密集型场景性能提升。

### 首次运行

```bash
git --version
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

mkdir hello-git && cd hello-git
git init
echo "# hello" > README.md
git add README.md
git commit -m "Initial commit"
```

### 验证是否成功

- `git --version` 输出预期版本号（建议 2.40 及以上）。
- `git config --list --global` 可看到已设置的 `user.name` 与 `user.email`。
- 上述示例仓库中 `git log --oneline` 显示 Initial commit。
- `git help tutorial` 或访问 [git-scm.com/doc](https://git-scm.com/doc) 确认文档可访问。

### 常见坑 / 注意事项

- **Git ≠ GitHub**：Git 是本地 VCS；远程协作需自行添加 `remote` 或使用 GitHub/GitLab 等托管服务。
- **首次提交前必须配置身份**：未设置 `user.name`/`user.email` 会导致 commit 失败或作者信息缺失。
- **大文件与二进制**：Git 不适合频繁变更的大二进制；应使用 [Git LFS](https://git-lfs.com/) 或外部制品仓库，避免仓库体积膨胀。
- **rebase 与 force push**：在共享分支上 `rebase` 后 `push --force` 可能覆盖他人历史；团队应约定 protected branch 与 merge/rebase 策略。
- **源码仓库 vs 日常使用**：clone 本 repo 用于贡献 Git 本身；日常项目只需安装 Git 二进制并在业务仓库中 `git init`/`clone` 即可。
- **许可证**：Git 以 GPLv2 分发；嵌入或修改分发时需遵守 GPL 义务；作为命令行工具日常使用通常无额外限制。

---

# Memos

> 开源自托管轻量笔记，Markdown 原生，时间线优先，快速捕获碎片想法。

- 页面：https://www.niceshare.site/github/memos/
- 仓库：https://github.com/usememos/memos
- 官网：https://usememos.com
- 语言：Go
- Stars：60928
- 许可证：MIT
- 标签：知识管理、本地优先、开发工具
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Memos 是一款开源、可自托管的轻量笔记工具，围绕「打开即写、写完即走」设计。界面以时间线为中心，不强调文件夹层级；笔记以 Markdown 存储，数据完全留在你的基础设施上，适合把 fleeting thoughts 快速沉淀成可检索的私有知识流。

## 核心特性

- **即时捕获** — 时间线优先 UI，打开页面即可记录，无需在目录间跳转
- **数据自主** — 自托管部署，Markdown 存储、零遥测，笔记可随时导出迁移
- **极简部署** — 单个 Go 二进制，Docker 镜像约 20MB，一条命令即可跑起来
- **多数据库后端** — 支持 SQLite、MySQL、PostgreSQL，从轻量个人到生产环境均可适配
- **开放集成** — MIT 许可，提供完整 REST 与 gRPC API，便于二次开发与自动化

## 对用户价值

碎片想法往往死在聊天窗口或临时便签里，既难检索又不可控。Memos 把「快速记录 → 时间线浏览 → 全文搜索」压缩成极轻流程，同时避免把私人笔记交给公有云。对开发者和小团队来说，它是比 Notion 更轻、比纯文本文件更易用的自托管中间层。

## 与替代方案

- 相比 **Logseq / Obsidian**，Memos 不做双链图谱与复杂知识库结构，强项是低摩擦捕获与时间线回顾，学习成本更低。
- 相比 **Notion / 飞书文档**，Memos 不面向协作文档与块级排版，而是个人或小型团队的私有碎片笔记；需要富文本协作时应选云端套件。
- 相比 **Flomo 等公网闪念工具**，Memos 数据留在自有服务器，隐私与合规可控，但需要自行维护部署与备份。
- 若需求是 OCR 扫描归档或企业文档管理，应评估 Paperless-ngx 等 DMS 方案；Memos 聚焦短笔记而非文件库。

## 适应人群

- 想自建私有「闪念 / 日记 / 技术备忘」流，又不想维护重型知识库的开发者。
- 已有 Homelab、NAS 或 VPS，希望用 Docker 快速跑一套轻量笔记服务的 self-host 用户。
- 需要 REST/gRPC API 把笔记接入自动化脚本、Bot 或内部工具链的工程团队。

## 如何使用

### 前置条件

- 推荐环境：任意可运行 Docker 的 Linux/macOS 主机，或支持原生二进制的桌面系统。
- 默认端口 `5230` 需可访问；持久化目录用于存放 SQLite 数据或挂载外部数据库配置。
- 了解 MIT 许可；生产环境请限制公网暴露、启用 HTTPS，并定期备份数据卷。

### 安装方式

Docker（官方推荐）：

```bash
docker run -d \
  --name memos \
  -p 5230:5230 \
  -v ~/.memos:/var/opt/memos \
  neosmemo/memos:stable
```

原生二进制（Linux / macOS / Windows）：

```bash
curl -fsSL https://raw.githubusercontent.com/usememos/memos/main/scripts/install.sh | sh
```

生产环境还可选用 [Docker Compose](https://usememos.com/docs/deploy)、预编译包、Kubernetes Helm 或源码构建，详见[官方部署文档](https://usememos.com/docs/deploy)。

### 首次运行

容器或二进制启动后，浏览器访问 `http://localhost:5230`，按引导创建首个管理员账号。在首页时间线直接输入 Markdown 内容并发布，确认笔记出现在列表中。

### 验证是否成功

- Web UI 可正常登录，新建笔记即时出现在时间线。
- 重启容器或进程后，历史笔记仍可从挂载的 `~/.memos` 数据目录恢复。
- 可选：调用 REST API 列出 memo，确认集成路径可用（见[文档](https://usememos.com/docs)）。

### 常见坑 / 注意事项

- 未挂载 `-v ~/.memos:/var/opt/memos` 时，容器删除会导致 SQLite 数据丢失。
- 从 SQLite 迁移到 MySQL/PostgreSQL 需按官方文档操作，勿直接拷贝数据库文件。
- Memos 不是团队 Wiki 或双链知识库，复杂结构化知识仍建议配合 Logseq、Obsidian 等工具。
- 升级前建议备份数据卷；可先访问[在线 Demo](https://demo.usememos.com/) 体验交互再决定是否自托管。

---

# Astro

> 面向内容驱动站点的现代 Web 框架，默认零 JS，支持 Islands 按需水合与多框架集成。

- 页面：https://www.niceshare.site/github/astro/
- 仓库：https://github.com/withastro/astro
- 官网：https://astro.build
- 语言：TypeScript
- Stars：60310
- 许可证：MIT
- 标签：开发工具、前端、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Astro 是由 [withastro](https://github.com/withastro) 维护的现代 Web 框架，主打**内容驱动网站**：博客、文档、营销落地页与作品集等以 Markdown、MDX 或 `.astro` 组件为主的站点。它采用 **Islands 架构**——默认不向浏览器发送 JavaScript，仅在需要交互的 UI 区域按需水合（React、Vue、Svelte、Solid 等均可通过官方集成接入）。本仓库为 Astro 核心、`create-astro` 脚手架及 `@astrojs/*` 官方集成 monorepo；文档站主题 [Starlight](https://github.com/withastro/starlight) 在独立仓库维护。

## 核心特性

- **Islands 与零 JS 默认**：静态 HTML 优先，交互组件可声明 `client:*` 指令按需加载，显著降低首屏脚本体积
- **`.astro` 单文件组件**：模板、脚本与样式同文件编写，语法接近 HTML，学习成本相对平缓
- **Content Collections**：通过 `astro:content` 为 Markdown/MDX frontmatter 提供 TypeScript 类型校验与统一内容管理
- **多框架与集成生态**：`astro add` 一键接入 React、Vue、Svelte、MDX、Tailwind、SSR 适配器（Node、Vercel、Netlify、Cloudflare 等）
- **灵活输出模式**：支持静态站点生成（SSG）、服务端渲染（SSR）与混合预渲染，文件路由与动态路由并存

## 对用户价值

内容型站点往往「大部分页面只需 HTML」，却在 React/Next 等全栈方案里背负不必要的客户端运行时。Astro 把性能优化前移到构建阶段：默认零 JS 让 Lighthouse 与 SEO 基线更友好，又能在同一项目里局部引入熟悉的 UI 框架组件，避免为整站绑定单一前端栈。若团队要同时维护官网、博客与文档，Astro 与 Starlight 可共用工具链；若已有 Vite 经验，`create astro` 几分钟即可本地预览，降低从评估到上线的摩擦。

## 与替代方案

- 相比 [Next.js](https://nextjs.org/)（React 全栈），Astro 更强调**内容站与静态优先**，默认不强制 React 运行时；Next 在 App Router、全栈 API 与 React 生态深度上更适合复杂交互型应用。
- 相比 [Gatsby](https://www.gatsbyjs.com/)（React SSG），两者都服务内容站点；Astro 的 Islands 模型与多框架集成更灵活，Gatsby 在 GraphQL 数据层与插件市场上历史积累更深。
- 相比 [Nuxt](https://nuxt.com/)（Vue 全栈）或 [SvelteKit](https://svelte.dev/docs/kit)（Svelte 全栈），Astro 不绑定单一 UI 框架，适合「主体是 Markdown/静态页 + 少量交互岛」的站点；若产品本质是重度 SPA 或强依赖某一框架的全栈能力，对应框架往往更自然。
- 相比 [Eleventy](https://www.11ty.dev/) 等静态站点生成器，Astro 提供组件化、Content Collections 与官方集成市场，抽象层级更高；极简单页或纯模板流水线场景，Eleventy 可能更轻。
- 边界说明：Astro 并非通用后台或实时协作平台方案；复杂多租户 CMS、重度客户端状态管理应用需评估是否引入 SSR 与 islands 之外的架构。

## 适应人群

- 需要高性能博客、营销站或作品集，并希望用 Markdown/MDX 管理内容的前端与独立开发者。
- 已在用 React/Vue/Svelte 组件库，希望在新内容站中**局部复用**而非整站迁移的团队。
- 技术文档、开源项目官网维护者，计划搭配 [Starlight](https://starlight.astro.build/) 或自建 Content Collections 文档区。

## 如何使用

### 前置条件

- Node.js 18+（以 [官方安装文档](https://docs.astro.build/en/install-and-setup/) 当前要求为准）。
- npm、pnpm 或 Yarn 等包管理器。
- 可选：浏览器访问 [astro.new](https://astro.new/) 在线体验模板，无需本地环境。

### 安装方式

**方式一：新建项目（推荐）**

```bash
npm create astro@latest
```

使用 pnpm 时：

```bash
pnpm create astro@latest
```

向导中可选择官方模板（博客、文档、基础等）与 TypeScript、Tailwind 等选项。

**方式二：手动安装到现有目录**

```bash
npm install astro
```

随后按文档配置 `astro.config.mjs` 与 `package.json` 脚本（适合已有 Vite 工程增量接入）。

### 首次运行

进入项目目录启动开发服务器：

```bash
npm run dev
```

终端会输出本地预览 URL（默认 `http://localhost:4321`）。在 `src/pages/` 下新增 `.astro` 或 `.md` 文件即可生成路由；使用 Content Collections 时内容通常放在 `src/content/` 并由 `src/content.config.ts` 注册集合。

### 验证是否成功

- 浏览器打开 dev server URL，默认欢迎页可正常渲染且无控制台阻塞性错误。
- 修改 `src/pages/index.astro` 或内容文件后，保存应触发热更新。
- 运行 `npm run build` 成功产出 `dist/`；`npm run preview` 可本地预览生产构建结果。

### 常见坑 / 注意事项

- **Islands 水合**：交互组件需显式添加 `client:load`、`client:visible` 等指令，否则仅以静态 HTML 输出；过度水合会抵消零 JS 优势。
- **集成与适配器**：SSR 部署需安装对应 `@astrojs/node`、`@astrojs/vercel` 等适配器；用 `npx astro add <integration>` 可自动写入配置，减少手写错误。
- **版本升级**：使用 `npx @astrojs/upgrade` 同步升级 Astro 与官方集成，升级前阅读 [CHANGELOG](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) 中的破坏性变更。
- **求助渠道**：查阅 [官方文档](https://docs.astro.build/)、[astro.new](https://astro.new/) 示例，或加入 [Astro Discord](https://astro.build/chat) 的 `#support` 频道。

---

# Taste Skill

> 面向 AI 编程助手的反「AI 味」前端 Agent Skill，用排版、动效与间距规则提升界面质感。

- 页面：https://www.niceshare.site/github/taste-skill/
- 仓库：https://github.com/Leonxlnx/taste-skill
- 官网：https://tasteskill.dev
- 语言：JavaScript
- Stars：58539
- 许可证：MIT
- 标签：AI 编程、Agent、开发工具
- 收录：2026-07-06（更新于 2026-07-06）

## 项目介绍

Taste Skill 是一套可移植的 **Agent Skills**，专门解决 AI 生成前端时常见的「千篇一律、缺乏层次」问题。默认技能会从需求推断设计语言，通过布局方差、动效强度、视觉密度三组拨盘约束排版、字体、间距与 GSAP 动效；仓库还包含极简、高端柔和、工业粗野等多种视觉变体，以及网页/移动端/品牌板的图像生成技能，可与 ChatGPT Images 等工具配合后交给 Codex、Cursor 或 Claude Code 实现。

## 核心特性

- **design-taste-frontend（v2 实验版）**：默认技能，含设计系统映射、反 em-dash 规则、GSAP 代码骨架与交付前检查清单
- **多风格实现技能**：gpt-taste（更严 Codex 规则）、soft / minimalist / brutalist 等按视觉方向选用
- **图像优先工作流**：image-to-code 生成参考图再编码；imagegen-frontend-web / mobile / brandkit 专产设计稿
- **存量项目改造**：redesign-existing-projects 先审计 UI 再修复层级与间距
- **可调设计拨盘**：DESIGN_VARIANCE、MOTION_INTENSITY、VISUAL_DENSITY（1–10）控制布局实验度与动效深度
- **Agent Skills 兼容**：通过 `npx skills add` 安装，亦可将 `SKILL.md` 复制到项目或对话中

## 对用户价值

用 AI 写界面时，模型往往输出居中卡片、通用配色与半成品注释。Taste Skill 把反 slop 规则、动效范式与交付纪律写进技能文件，让助手在生成代码前先做设计语言推断与自检，显著减少「看起来像 AI 做的」模板感。图像类技能还能先产出可评审的视觉稿，再进入实现阶段，适合 landing page、产品官网与品牌探索等需要「有品味」的前端任务。

## 与替代方案

- 相比 [UI UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) 的行业设计系统检索，Taste Skill 更侧重 **反模板化前端实现**、GSAP 动效与多视觉人格（极简/粗野/高端），而非大规模配色数据库。
- 相比 [Anthropic skills](https://github.com/anthropics/skills) 等通用技能规范仓库，本仓库是 **专注前端质感** 的成品技能集，开箱即装，默认 v2 仍在实验迭代。
- 相比手写 Cursor Rules，技能可按 `--skill` 精确安装单个子能力，并与 vercel-labs agent-skills CLI 生态对齐。
- 图像技能只产出参考图，**不替代**设计工具的最终交付；框架无关，但动效示例以 GSAP 为主。

## 适应人群

- 用 Cursor、Codex 或 Claude Code 做 landing page / 产品官网，希望界面更精致的开发者。
- 需要「先出视觉稿再写代码」或改造存量项目 UI 的独立开发者与小团队。
- 正在搭建多 Agent 前端工作流、希望统一反 slop 设计纪律的效率型用户。

## 如何使用

### 前置条件

- Node.js 环境（用于 `npx skills add`）。
- 已安装目标 AI 编程助手（Cursor、Codex、Claude Code 等）。
- 使用图像生成技能时，需具备 ChatGPT Images、Codex 图像模式或同类图像生成能力。

### 安装方式

**安装全部技能（推荐）**

```bash
npx skills add https://github.com/Leonxlnx/taste-skill
```

**仅安装默认前端技能**

```bash
npx skills add https://github.com/Leonxlnx/taste-skill --skill "design-taste-frontend"
```

**固定使用 v1 行为（若 v2 实验版影响现有流程）**

```bash
npx skills add https://github.com/Leonxlnx/taste-skill --skill "design-taste-frontend-v1"
```

亦可直接将仓库内对应 `SKILL.md` 复制到项目，或粘贴进 ChatGPT / Codex 对话。

### 首次运行

安装默认技能后，用自然语言描述页面需求，例如「为 AI 笔记产品做一个 landing page」。若走图像优先流程，在 prompt 中写明：`follow the skill: generate images, then analyze, then code`。需要特定视觉方向时，额外安装 `high-end-visual-design`、`minimalist-ui` 或 `industrial-brutalist-ui` 等子技能。

### 验证是否成功

确认 `npx skills add` 无报错，且助手对话中能识别技能指令（布局、间距、动效约束明显区别于未安装时）。使用 image-to-code 时，应先后看到参考图分析与对应前端实现，而非跳过图像阶段。

### 常见坑 / 注意事项

- 默认 `design-taste-frontend` 已为 **v2 实验版**，重装会覆盖 v1；依赖旧行为请显式安装 `design-taste-frontend-v1`。
- `--skill` 参数须使用 SKILL frontmatter 中的 **install name**（如 `design-taste-frontend`），而非文件夹名 `taste-skill`。
- 项目声明 **无官方代币**；任何借用项目名称的加密资产均未获背书。
- v2 仍在向稳定版迭代，生产环境关键页面建议人工评审视觉与无障碍；升级前阅读 [CHANGELOG](https://www.tasteskill.dev/changelog)。

---

# Zustand

> React 生态轻量状态管理库，Hook 驱动、无需 Provider，经实战验证的并发与重渲染安全。

- 页面：https://www.niceshare.site/github/zustand/
- 仓库：https://github.com/pmndrs/zustand
- 官网：https://zustand.docs.pmnd.rs
- 语言：TypeScript
- Stars：58351
- 许可证：MIT
- 标签：开发工具、前端、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Zustand 由 [pmndrs](https://github.com/pmndrs) 维护，是 React 生态中体量极小、下载量极高的状态管理方案。它基于简化的 Flux 思想，以 `create` 返回的 Hook 作为 Store 入口，API 直观、样板代码少，且**不需要**用 Context Provider 包裹应用。项目在 zombie child、React 并发渲染与混合渲染器下的 context 丢失等常见陷阱上投入了大量工程验证，适合作为中大型 React 应用的默认全局状态层。官方提供 [在线 Demo](https://zustand-demo.pmnd.rs/) 与完整 [文档站](https://zustand.docs.pmnd.rs/)。

## 核心特性

- **Hook 即 Store**：`create` 生成 `useXxxStore`，state 可包含原始值、对象与 action 函数；`set` 默认浅合并更新
- **按需订阅**：组件通过 selector 选取状态切片，仅在所选切片变化时重渲染；支持 `useShallow` 做多字段浅比较
- **无 Provider 架构**：任意组件直接调用 Store Hook，避免 Context 嵌套与「包裹地狱」
- **组件外访问**：`getState`、`setState`、`subscribe` 可在事件回调、路由守卫等非组件代码中读写状态
- **中间件生态**：内置 `persist`、`immer`、`devtools`、`redux` 等中间件，可按需叠加持久化与调试能力
- **框架无关核心**：`zustand/vanilla` 的 `createStore` 可在无 React 环境使用，再通过 `useStore` 绑定到组件

## 对用户价值

跨页面共享用户会话、购物车、主题或 UI 状态时，仅靠 props 下钻或手写 Context 很快难以维护。Zustand 把全局状态收敛到独立 Store，组件按 selector 精确订阅，避免「整棵子树因一次更新而重渲染」。相比 Redux，省去 action types、reducers 与 Provider 样板；相比纯 Context，具备细粒度订阅与成熟的并发安全处理。对需要 DevTools、持久化或 Redux 式 reducer 的团队，可通过中间件渐进增强，而不必一开始就引入重型架构。

## 与替代方案

- 相比 [Redux](https://redux.js.org/) / [Redux Toolkit](https://redux-toolkit.js.org/)，Zustand 更轻、更少仪式化：默认无 Provider、无强制 reducer 分层；需要 Redux DevTools 或 reducer 风格时可加 `devtools` / `redux` 中间件。大型团队若已深度投入 RTK 生态，迁移需评估现有中间件与规范成本。
- 相比 [React Context](https://react.dev/reference/react/createContext)，Zustand 减少样板代码，且默认只在 selector 返回值变化时触发重渲染；Context 适合**低频变更、局部子树**的依赖注入，高频全局状态更宜 Zustand。
- 相比 [Jotai](https://jotai.org/) / [Recoil](https://recoiljs.org/)（原子化状态），Zustand 以单一 Store 对象为中心，心智模型更接近传统 Flux；原子库适合细粒度派生图与组合式依赖，选型取决于团队更习惯「Store 切片」还是「原子图」。
- 相比 [Pinia](https://github.com/vuejs/pinia)（Vue 生态），Zustand 深度绑定 React Hooks 与并发模型；跨框架项目应按技术栈分别选型，勿强行类比。
- 边界说明：Zustand 刻意保持「不固执己见」；极复杂的状态机、时间旅行调试或严格单向数据流规范，可能仍需 Redux 或专用方案。在 Next.js App Router 的 Server Components 中，勿在 RSC 内用 `getState`/`setState` 写客户端状态（见官方 [#2200](https://github.com/pmndrs/zustand/discussions/2200) 讨论）。

## 适应人群

- 使用 React 18+ 或 Next.js 构建中后台、电商、SaaS 等需要跨路由共享状态的前端工程师。
- 觉得 Redux 过重、Context 性能与样板难以接受，希望用最小 API 落地全局状态的团队。
- 需要 persist、Immer、DevTools 等能力，但希望以中间件按需扩展而非一开始引入完整框架的全栈开发者。

## 如何使用

### 前置条件

- 已具备 React 16.8+ 项目（Vite、Create React App、Next.js 等），Node.js 与 npm、pnpm 或 Yarn。
- TypeScript 项目建议阅读官方 [TypeScript 指南](https://zustand.docs.pmnd.rs/learn/guides/beginner-typescript)；使用 `devtools` 中间件时需安装 `@redux-devtools/extension` 类型。
- 浏览器安装 [Redux DevTools 扩展](https://chromewebstore.google.com/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd)（可选，配合 `devtools` 中间件）。

### 安装方式

```bash
npm install zustand
```

使用 pnpm 或 Yarn 时，将 `npm install` 替换为 `pnpm add zustand` 或 `yarn add zustand`。

可选中间件无额外安装步骤（如 `persist`、`immer` 从 `zustand/middleware` 导入）；若 Store 内使用 Immer 写法，需另行 `npm install immer`。

### 首次运行

创建第一个 Store（建议放在 `src/stores/` 或 `store/`）：

```jsx
import { create } from 'zustand'

const useBearStore = create((set) => ({
  bears: 0,
  increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
  removeAllBears: () => set({ bears: 0 }),
}))
```

在组件中按 selector 订阅：

```jsx
function BearCounter() {
  const bears = useBearStore((state) => state.bears)
  return <h1>{bears} around here ...</h1>
}

function Controls() {
  const increasePopulation = useBearStore((state) => state.increasePopulation)
  return <button onClick={increasePopulation}>one up</button>
}
```

TypeScript 项目推荐：

```ts
import { create } from 'zustand'

interface BearState {
  bears: number
  increase: (by: number) => void
}

const useBearStore = create<BearState>()((set) => ({
  bears: 0,
  increase: (by) => set((state) => ({ bears: state.bears + by })),
}))
```

也可在 [官方 Demo](https://zustand-demo.pmnd.rs/) 或文档 [快速入门](https://zustand.docs.pmnd.rs/learn/getting-started/introduction) 中在线体验。

### 验证是否成功

- 应用启动无控制台报错，页面正常渲染。
- 点击触发 `increasePopulation` 后，`BearCounter` 中 `bears` 数值同步更新。
- 仅订阅 `increasePopulation` 的组件在 `bears` 变化时不应多余重渲染（可用 React DevTools Profiler 观察）。
- 若启用 `devtools` 中间件，Redux DevTools 中应出现对应 Store 的 `setState` 记录。

### 常见坑 / 注意事项

- **避免全量订阅**：`const state = useBearStore()` 会在任意 state 变化时重渲染该组件；应始终用 selector 选取所需字段。
- **多字段选择**：构造对象或数组 selector 时用 `useShallow`（`zustand/react/shallow`），否则引用变化会导致多余渲染。
- **`set` 的替换模式**：`set(partial, true)` 会替换整个 state 而非合并，误用可能清空 actions 等字段。
- **Next.js RSC**：勿在 Server Components 中通过 `getState`/`setState` 操作客户端 Store；客户端状态应在 Client Component 内初始化与消费。
- **中间件与 vanilla API**：修改 `set`/`get` 的中间件可能不会作用于 `getState`/`setState` 的 vanilla 调用，跨边界读写时需对照文档。
- **从 Redux 迁移**：可先保留 reducer 语义（`redux` 中间件或手写 `dispatch`），再逐步简化为直接 `set` 的 action 函数；大型项目建议按 Store 边界分批迁移。

---

# Claude Code Best Practice

> Claude Code 最佳实践知识库，从 vibe coding 到 Agent 工程化，覆盖原语、工作流与 80+ 条社区技巧。

- 页面：https://www.niceshare.site/github/claude-code-best-practice/
- 仓库：https://github.com/shanraisshan/claude-code-best-practice
- 语言：HTML
- Stars：58337
- 许可证：MIT
- 标签：AI 编程、Agent、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Claude Code Best Practice 是由 shanraisshan 维护的 **Claude Code 实践知识库**，口号是「从 vibe coding 到 agentic engineering」。仓库把官方文档、Boris Cherny 等核心成员的公开建议与社区高赞工作流汇总成可检索的结构：涵盖 Subagents、Commands、Skills、Hooks、MCP、Settings 等原语，并附带 `best-practice/` 指南与 `implementation/` 可运行示例。README 还横向对比 Superpowers、gstack、OpenSpec 等十余套主流研发工作流，适合当作 Claude Code 的「课程式参考书」而非单一技能包。

## 核心特性

- **原语全景图**：Subagents、Commands、Skills、Hooks、MCP、Plugins、Memory、Checkpointing 等概念均有最佳实践文档与实现索引
- **编排示范**：`/weather-orchestrator` 演示 **Command → Agent（预载 Skill）→ Skill** 完整编排链路，含天气 SVG 输出
- **工作流横评**：对照 Superpowers、Everything Claude Code、Spec Kit、gstack、OpenSpec 等项目的 Research → Plan → Execute → Review → Ship 模式
- **跨模型协作**：收录 Plugin、MCP、Router 三类与 Codex、Gemini、本地模型联用的方案与工具清单
- **83 条 Tips**：按 Prompting、Planning、Context、Session、CLAUDE.md、Agents、Hooks 等分类，来源标注至 Claude 团队或社区
- **🔥 Hot 专题**：Ultrareview、Auto Mode、Agent Teams、Ralph Wiggum Loop、Git Worktrees 等新特性的实践链接与实现仓库

## 对用户价值

Claude Code 能力迭代极快，官方文档、X 帖与工作流仓库分散在各处，新手容易把 Agent 当聊天机器人用、老手也难以及时跟进新原语。本仓库把「该用什么原语、如何编排、业界怎么玩」收敛到一处：你可以先跑通 `/weather-orchestrator` 理解编排模式，再按 Tips 优化自己的 `CLAUDE.md`，或对照工作流表选型 Superpowers / OpenSpec 等方案。对团队而言，它是可共享的 onboarding 教材；对个人而言，可减少反复搜索碎片教程的时间。

## 与替代方案

- 相比 [Anthropic 官方文档](https://code.claude.com/docs)，本仓库提供 **社区技巧聚合、工作流横评与可克隆实现**，更像策展索引而非 API 参考手册。
- 相比 [Superpowers](https://github.com/obra/superpowers) 等**可安装的技能方法论**，这里是 **Claude Code 生态地图 + 参考实现**；若你需要开箱即用的 TDD / 子代理技能链，应直接安装 Superpowers，再用本库理解其在全局中的位置。
- 相比 [Everything Claude Code](https://github.com/affaan-m/everything-claude-code) 等**大而全配置合集**，本库侧重 **概念解释、编排模式与来源可追溯的 Tips**；若目标是快速复制一套 `.claude/` 配置，ECC 可能更直接。
- 本仓库 **不负责模型路由或 CLI 代理**；跨模型需求请配合文中列出的 claude-code-router、codex-plugin-cc 等专用工具。

## 适应人群

- 已安装 Claude Code，想系统理解 Agents / Commands / Skills / Hooks 如何组合编排的开发者。
- 需要在团队内建立 Claude Code 最佳实践共识、挑选工作流框架的 Tech Lead。
- 关注 Boris Cherny、Thariq 等官方成员动态，希望有一份持续更新的中文友好索引的效率型用户。

## 如何使用

### 前置条件

- 已安装 [Claude Code CLI](https://code.claude.com/docs/en/quickstart) 并完成 Anthropic 账号认证。
- 本机有 Git；克隆仓库需要网络访问 GitHub。
- 理解本库定位为 **参考书 + 示例实现**，不是 npm 包或一键插件；核心收益来自阅读结构与在 Claude Code 内运行示例命令。

### 安装方式

克隆仓库到本地（可在独立目录学习，或 Fork 后按需拷贝 `.claude/` 片段到自己的项目）：

```bash
git clone https://github.com/shanraisshan/claude-code-best-practice.git
cd claude-code-best-practice
```

在仓库根目录启动 Claude Code：

```bash
claude
```

### 首次运行

在 Claude Code 会话中执行编排示范命令：

```bash
/weather-orchestrator
```

按提示选择摄氏或华氏温度单位；流程将依次调用 `weather-agent`（预载 `weather-fetcher` Skill）与 `weather-svg-creator` Skill。详见 [orchestration-workflow 文档](https://github.com/shanraisshan/claude-code-best-practice/blob/main/orchestration-workflow/orchestration-workflow.md)。

### 验证是否成功

执行完成后应生成：

- `orchestration-workflow/weather.svg` — 天气 SVG 卡片
- `orchestration-workflow/output.md` — 温度摘要

终端会显示所取温度、单位与文件路径。若启用了作者推荐的 [Claude Code Hooks](https://github.com/shanraisshan/claude-code-hooks)，工作过程中还可听到自定义提示音。

### 常见坑 / 注意事项

- README 明确建议 **把本库当课程阅读，而非照搬整套工作流**；应先理解原语，再组装适合自己的流程。
- 不要把 Claude 当普通聊天机器人；价值在于 Commands、Agents、Skills 等 **可组合原语**。
- `🔥 Hot` 与 `implementation/` 中的高级特性（如 Ralph Wiggum Loop）有独立仓库，需单独克隆研读，并非全部内置于主仓库。
- 仓库体量大、链接多，建议从 [How to Use](https://github.com/shanraisshan/claude-code-best-practice#get-the-maximum-out-of-this-repo-by-following-these-steps) 七步指引入手，再按需深入 `tips/` 与 `best-practice/`。
- Stars 与功能列表随 Claude Code 版本快速变化，实施前对照 [官方 Changelog](https://code.claude.com/docs) 核实命令是否仍可用。

---

# headroom

> AI Agent 上下文压缩层：在送入 LLM 前压缩工具输出、日志与 RAG，省 60–95% Token，答案不变。

- 页面：https://www.niceshare.site/github/headroom/
- 仓库：https://github.com/headroomlabs-ai/headroom
- 官网：https://headroom-docs.vercel.app/docs
- 语言：Python
- Stars：55691
- 许可证：Apache-2.0
- 标签：Agent、AI 编程、开发工具
- 收录：2026-07-03（更新于 2026-07-03）

## 项目介绍

Headroom 是面向 AI Agent 的**上下文压缩层**：在工具输出、日志、RAG 分块、文件与对话历史进入 LLM 之前完成压缩，官方宣称可节省 **60–95%** Token 且保持答案质量。数据默认在本地处理，支持 Python/TypeScript 库内联调用、零改代码的本地代理，以及 MCP 服务器三种接入方式，并可通过 `headroom wrap` 一键包裹 Claude Code、Codex、Cursor、Aider 等主流编码 Agent。

## 核心特性

- **三种接入模式**：`compress(messages)` 库调用、`headroom proxy` 透明代理、MCP 工具（`headroom_compress` / `headroom_retrieve` / `headroom_stats`）
- **内容感知压缩**：ContentRouter 按类型路由至 SmartCrusher（JSON）、CodeCompressor（多语言 AST）、Kompress-v2-base（文本）等压缩器
- **可逆压缩（CCR）**：原文本地缓存，模型需要时可按需检索，避免信息不可逆丢失
- **跨 Agent 共享记忆**：Claude、Codex、Gemini 等 Agent 共用存储，自动去重
- **Agent 一键包裹**：`headroom wrap claude|codex|cursor|aider|…`，`headroom unwrap` 可撤销
- **输出 Token 削减**：代理层可裁剪模型回复中的冗余寒暄与重复代码（`HEADROOM_OUTPUT_SHAPER=1`）
- **框架集成**：支持 Anthropic/OpenAI SDK、Vercel AI SDK、LiteLLM、LangChain、Agno 等

## 对用户价值

编码 Agent 日常会把大量工具返回、日志与检索结果塞进上下文，Token 账单随之膨胀。Headroom 在**不改业务代码**的前提下拦截并压缩这些内容——跑代理或 `wrap` 即可生效，库模式则可嵌入自有流水线。可逆 CCR 让模型在压缩后仍能取回原文，降低「压过头」的风险；跨 Agent 记忆则避免同一信息在 Claude Code 与 Codex 之间重复占用窗口。对个人开发者，这是降低 Opus 等高价模型成本的实用层；对团队，官方还提供企业级托管部署选项。

## 与替代方案

- 相比 **Anthropic/OpenAI 原生 Prompt Caching 或厂商内置压缩**，Headroom 强调**跨 Agent、跨提供商**的统一压缩层，并附带 CCR 可逆检索与内容类型路由；若你只用单一厂商且不需要跨工具记忆，原生方案可能更简单。
- 相比 **[LLMLingua](https://github.com/microsoft/LLMLingua)** 等**通用 Prompt 压缩研究工具**，Headroom 面向**Agent 工作负载**设计：内置 JSON/代码 AST 压缩器、代理模式、MCP 与 `wrap` 生态，开箱即可接入 Claude Code/Cursor 而非自行拼装流水线。
- 相比 **手动截断或会话摘要**，Headroom 提供**自动化、可度量**的压缩（`headroom perf`、`headroom dashboard`）与基准测试套件（`python -m headroom.evals suite`），并支持 `headroom learn` 从失败会话挖掘修正写入 `CLAUDE.md` 等。
- 相比 **仅做请求路由的 LiteLLM**，Headroom 可作为 LiteLLM Callback 叠加使用，专注**输入/输出 Token 削减**而非模型网关本身；二者可组合而非互斥。

## 适应人群

- 每天运行 **Claude Code、Cursor、Codex、Aider** 等编码 Agent，Token 成本敏感且希望零改代码降费的开发者。
- 需要在**多个 Agent 之间共享上下文记忆**，或希望压缩**工具输出、日志、RAG 分块**的 AI 应用工程师。
- 构建自有 Agent 流水线、希望通过**库/SDK/代理/MCP** 灵活接入，并重视**本地优先与可逆压缩**的技术团队。

## 如何使用

### 前置条件

- **Python 3.10+**（CLI 与完整功能通过 PyPI 安装）；TypeScript SDK 通过 npm 安装，**不含 `headroom` CLI**。
- 使用 Kompress-v2-base 等 ML 压缩器时需能访问 Hugging Face；企业网络需配置 `REQUESTS_CA_BUNDLE` 等 CA 信任（见 README 企业环境说明）。
- `headroom wrap` 与代理模式需在本地运行进程；纯沙箱且无本地进程权限的环境不适用。

### 安装方式

```bash
pip install "headroom-ai[all]"          # Python，含 headroom CLI
npm install headroom-ai                 # TypeScript SDK（仅库，无 CLI）
docker pull ghcr.io/chopratejas/headroom:latest
```

可选 extras：`[proxy]`、`[mcp]`、`[ml]`、`[code]`、`[memory]`、`[langchain]`、`[agno]` 等；`pipx` 用户建议指定 Python 3.13 以启用仪表盘美元节省统计。

### 首次运行

```bash
headroom wrap claude                    # 包裹 Claude Code（或其他 Agent）
# 或
headroom proxy --port 8787              # 启动透明代理，客户端指向本地端口
# 或库模式
python -c "from headroom import compress; print(compress([...]))"
```

### 验证是否成功

```bash
headroom doctor                         # 健康检查，确认路由正常
headroom perf                           # 查看压缩性能与节省比例
headroom dashboard                      # 实时节省仪表盘（需代理运行中）
```

### 常见坑 / 注意事项

- **`headroom` CLI 仅随 pip 包提供**，npm 包是 TypeScript 库，不要期望 `npx headroom` 可用。
- Python 3.14 上 Token 节省可统计，但仪表盘**美元金额**可能显示 `$0.00`（LiteLLM 兼容性限制）；建议 pipx 使用 Python 3.13。
- 企业 SSL 拦截环境安装失败时，需先安装 Rust 或使用 `--only-binary` 预编译 wheel；运行时还需信任 `cdn.pyke.io`（ONNX）与 `huggingface.co`（模型）。
- `HEADROOM_OUTPUT_SHAPER` 等环境变量对**已运行代理**需通过 `headroom wrap` 的热同步或重启生效；共享代理上为全局设置。
- 撤销包裹：`headroom unwrap claude`（支持 claude、copilot、codex、opencode、openclaw 等）。

---

# OpenSpec

> 面向 AI 编码助手的规范驱动开发框架，在写代码前先对齐需求、设计与任务清单。

- 页面：https://www.niceshare.site/github/openspec/
- 仓库：https://github.com/Fission-AI/OpenSpec
- 官网：https://openspec.dev/
- 语言：TypeScript
- Stars：55654
- 许可证：MIT
- 标签：AI 编程、Agent、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

OpenSpec 是由 Fission AI 维护的 **规范驱动开发（Spec-Driven Development, SDD）** 框架，专为 AI 编码助手设计。它把「先对齐再动手」落到可追踪的工件上：每个变更拥有独立文件夹，内含 proposal、specs、design 与 tasks，人类与 Agent 在写代码前就需求与方案达成共识。项目强调流动迭代而非瀑布门禁，既适合个人项目，也能扩展到团队协作的棕地代码库。

## 核心特性

- **Agree before you build**：人类与 AI 在编码前对齐规范，减少聊天上下文里的隐性假设
- **Stay organized**：每次变更生成 `openspec/changes/<name>/`，含 proposal、specs、design、tasks 四类工件
- **Work fluidly**：任意工件可随时更新，无僵化阶段门禁；支持 `/opsx:propose` → `/opsx:apply` → `/opsx:archive` 闭环
- **Use your tools**：通过斜杠命令与技能集成 Cursor、Claude Code、Codex 等 **25+** AI 助手
- **棕地友好**：面向已有代码库迭代，而非仅适用于从零开始的新项目
- **可配置工作流**：`openspec config profile` 可选扩展流程（`/opsx:new`、`/opsx:verify`、`/opsx:bulk-archive` 等）

## 对用户价值

许多 AI 结对编程会话把需求留在对话历史里，导致范围漂移、返工与不可预测输出。OpenSpec 增加一层轻量规范：Agent 先产出可审阅的 proposal 与任务清单，再按 tasks 逐项实现并归档，把「我们到底要做什么」变成仓库内的持久工件。对团队而言，变更有文件夹与归档记录可查；对个人而言，可在不引入重型流程的前提下获得 Spec Kit 类工具的结构化收益。

## 与替代方案

- 相比 GitHub [Spec Kit](https://github.com/github/spec-kit)，OpenSpec **更轻量**：无 Python 环境与严格阶段门禁，可随时修改任意工件，适合快速迭代。
- 相比 AWS [Kiro](https://kiro.dev) 等 IDE 绑定方案，OpenSpec **工具中立**：不锁定特定编辑器或模型，沿用你已有的 Cursor / Claude Code / Codex 等工作流。
- 相比 [Superpowers](https://github.com/obra/superpowers) 等 Agent 方法论技能库，OpenSpec 侧重 **仓库内规范工件与 CLI 初始化**，把 proposal/spec/tasks 落到 `openspec/` 目录；Superpowers 更偏会话内技能链编排，二者可互补而非互斥。
- 若你不需要任何规范层、只求单次快速 patch，直接对话即可；OpenSpec 的价值在于 **可重复、可归档、可协作** 的变更管理。

## 适应人群

- 使用 Cursor、Claude Code、Codex 等工具，希望 Agent 先产出 proposal 与 tasks 再写代码的开发者。
- 在棕地项目或多人协作中，需要把 AI 辅助变更留下可追溯记录的 Tech Lead。
- 评估过 Spec Kit 但觉得流程过重，想要更灵活 SDD 工作流的效率型用户。

## 如何使用

### 前置条件

- **Node.js 20.19.0 或更高版本**（README 明确要求）。
- 目标目录为 Git 项目（或计划纳入版本管理的代码库）。
- 已安装并启用 README [支持列表](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md) 中的某一 AI 助手；不同工具需按其文档完成斜杠命令或技能安装。
- 推荐使用高推理能力模型（官方建议 Codex 5.5、Opus 4.7 等）做规划与实现；实施前清空上下文以保持窗口整洁。

### 安装方式

全局安装 CLI（亦支持 pnpm、yarn、bun、nix，见 [installation.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/installation.md)）：

```bash
npm install -g @fission-ai/openspec@latest
```

在项目根目录初始化：

```bash
cd your-project
openspec init
```

若需扩展工作流，可配置 profile 后更新 Agent 指令：

```bash
openspec config profile
openspec update
```

### 首次运行

在 Agent 对话中发起提案，例如：

```text
/opsx:propose add-dark-mode
```

Agent 应在 `openspec/changes/add-dark-mode/` 下生成 proposal、specs、design、tasks。确认后执行 `/opsx:apply` 按 tasks 实现，完成后用 `/opsx:archive` 归档并更新主规范。

### 验证是否成功

- 运行 `openspec init` 后项目内出现 `openspec/` 目录与 Agent 集成文件。
- `/opsx:propose` 能创建完整变更文件夹且四类工件可读。
- `/opsx:apply` 按 tasks 推进，`/opsx:archive` 将变更移入 archive 并更新 specs。
- 升级包后执行 `openspec update` 可刷新各工具的斜杠命令与技能定义。

### 常见坑 / 注意事项

- 升级 CLI 后务必在各项目内执行 `openspec update`，否则 Agent 可能仍使用旧版斜杠命令。
- OpenSpec 默认收集匿名遥测（仅命令名与版本）；CI 中自动禁用，本地可设 `OPENSPEC_TELEMETRY=0` 或 `DO_NOT_TRACK=1` 关闭。
- 较大功能贡献需先提 OpenSpec change proposal 与上游对齐；小修复可直接 PR。
- 社区 schema 与工作流定制见 [customization.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md)；问题可走 [Discord](https://discord.gg/YctCnvvshC) 或 GitHub Issues。

---

# Impeccable

> 面向 AI 编程助手的设计语言：1 个 Skill、23 条命令、浏览器实时迭代与 60 条确定性检测规则。

- 页面：https://www.niceshare.site/github/impeccable/
- 仓库：https://github.com/pbakaus/impeccable
- 官网：https://impeccable.style
- 语言：JavaScript
- Stars：52428
- 许可证：Apache-2.0
- 标签：AI 编程、Agent、开发工具
- 收录：2026-07-29（更新于 2026-07-29）

## 项目介绍

Impeccable 是一套给 AI 编程助手用的**前端设计语言与工作流**：在 Anthropic `frontend-design` 技能思路上扩展，提供统一的 `/impeccable` 命令入口、浏览器实时视觉迭代，以及无需 LLM、无需 API Key 的确定性检测器。先用 `/impeccable init` 写出 `PRODUCT.md` / `DESIGN.md`，后续 `craft`、`audit`、`polish`、`live` 等命令就能在同一套受众、品牌、色彩与反参考语境下改界面，减少「每家官网都像同一套 SaaS 模板」的问题。

## 核心特性

- **一次初始化**：`/impeccable init` 区分 brand（营销/落地页）与 product（应用 UI），写入受众、语气、反参考与设计系统上下文
- **23 条共享命令**：`craft`、`shape`、`critique`、`audit`、`polish`、`bolder` / `quieter`、`animate`、`live` 等，形成可复用的设计词汇
- **60 条确定性检测规则**：CLI 与浏览器扩展可在无 LLM 情况下扫描 AI slop（紫蓝渐变、嵌套卡片、bounce 缓动等）与通用质量问题
- **设计 Hook**：安装后可在 Claude Code、Cursor、Codex、Copilot、Grok Build 等对 UI 文件改动自动跑检测；Cursor 可在写入前拦截
- **多工具一键安装**：`npx impeccable install` 适配 Cursor、Claude Code、Codex、Gemini CLI、OpenCode 等主流 harness

## 对用户价值

模型训练语料高度同质，跳过设计引导时几乎总会出现 Inter、紫到蓝渐变、卡片套卡片、彩色底上的灰字等「一眼 AI」痕迹。Impeccable 把产品语境、反模式清单与可执行命令写进助手技能，让你在写代码前先定调、在改完后用 `audit` / `critique` / `polish` 收口；`npx impeccable detect` 还能在 CI 或本地做确定性扫描，不依赖模型发挥。

## 与替代方案

- 相比 [Taste Skill](https://github.com/Leonxlnx/taste-skill) 侧重多视觉人格与 GSAP 动效范式，Impeccable 更强调 **命令式设计工作流**（init → shape/craft → audit/polish）与 **无 LLM 的确定性检测器**。
- 相比 [UI UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) 的行业风格/配色数据库检索，本仓库更像「设计语言 + 迭代命令 + Hook」，而不是大规模设计系统生成器。
- 相比仅安装 Anthropic [frontend-design](https://github.com/anthropics/skills/tree/main/skills/frontend-design) 通用技能，Impeccable 补齐了项目级 `PRODUCT.md`/`DESIGN.md`、23 条命令、live 模式与 CLI detect。
- 它**不替代** Figma / 专业设计评审；品牌强约束项目仍需人工 override 检测忽略项与设计 token。

## 适应人群

- 用 Cursor、Claude Code、Codex 等做落地页 / SaaS 前端，想压住「AI 味」模板感的开发者。
- 需要团队统一设计命令与检测规则、并希望 Hook / CI 扫描兜底的小团队。
- 正在搭建多 harness Agent 工作流、希望一套 Skill 覆盖多工具的效率型用户。

## 如何使用

### 前置条件

- Node.js 环境（用于 `npx impeccable`）。
- 已安装目标 AI 编程工具（Cursor、Claude Code、Codex、Gemini CLI 等）。
- Cursor 使用 Skills 时，需按官方文档开启 Agent Skills（必要时切换 Nightly / 启用 Rules 中的 Skills）。

### 安装方式

**推荐：CLI 安装**

```bash
npx impeccable install
```

安装器会检测 `~/.claude`、`~/.codex`、`.cursor` 等目录，可交互选择 provider 与项目/全局作用域；脚本场景可用：

```bash
npx impeccable install --providers=claude,codex,cursor,grok --scope=project
```

更新已有安装：

```bash
npx impeccable update
```

**备选：Claude Code 插件市场**

```bash
/plugin marketplace add pbakaus/impeccable
```

然后在 `/plugin` 中安装 Impeccable。完整文档见 [impeccable.style](https://impeccable.style)。

### 首次运行

重载 harness 后，在项目中运行：

```text
/impeccable init
```

按提示选择 brand 或 product 表面，生成设计上下文。之后可按需执行，例如：

```text
/impeccable craft
/impeccable audit landing
/impeccable polish settings
/impeccable live
```

常用命令可用 `/impeccable pin audit` 固定为独立快捷方式（如 `/audit`）。Codex 用户安装或更新后需打开 `/hooks` 批准项目 Hook。

### 验证是否成功

- 助手中可看到 `/impeccable`（或 Codex 的 `$impeccable` / `/skills`）且命令列表可用。
- `init` 后项目出现 `PRODUCT.md`，并按选择生成或约定 `DESIGN.md`。
- 可选验证检测器：`npx impeccable detect src/` 能输出规则命中（或干净扫描结果），无需 API Key。

### 常见坑 / 注意事项

- **Codex Hook 信任**：更新若改动 `.codex/hooks.json`，可能需再次在 `/hooks` 中批准。
- **Grok**：项目 Hook 需 `/hooks-trust` 或启动时 `--trust` 后才会执行。
- **`.impeccable/` 勿整目录提交**：截图、session、本地缓存应 gitignore；保留共享的 `config.json`、`design.json`、`critique/*.md` 等（见 README 模板）。
- **忽略规则**：品牌字体等合法例外可用 `npx impeccable ignores` 或文件内 `impeccable-disable` 注释，避免误报。
- 手动 `cp -r dist/...` 仅作兜底；日常以 `npx impeccable install` / `update` 为准。

---

# Claude Cookbooks

> Anthropic 官方 Claude 食谱集，以 Jupyter Notebook 演示工具调用、RAG、多模态、Agent 与评测实践。

- 页面：https://www.niceshare.site/github/claude-cookbooks/
- 仓库：https://github.com/anthropics/claude-cookbooks
- 语言：Jupyter Notebook
- Stars：50504
- 许可证：MIT
- 标签：AI 编程、Agent、工作流
- 收录：2026-07-28（更新于 2026-07-28）

## 项目介绍

Claude Cookbooks 是 Anthropic 维护的 **Claude 官方示例食谱库**，用可复制的 Jupyter Notebook / Python 片段展示如何用 Claude API 落地真实能力：分类与摘要、RAG、工具调用、多模态、Extended Thinking、Claude Agent SDK、Managed Agents、评测与可观测性等。仓库通过 `registry.yaml` 索引约 80+ 道配方，并配套 `uv` 依赖管理与 notebook 校验流水线，适合当作「官方可运行文档」而非纯概念教程。

## 核心特性

- **能力配方**：分类、摘要、知识图谱、RAG 与检索增强等基础能力示例
- **工具与 Agent**：Tool Use、Agent Patterns、威胁情报 Agent、客服 Agent 等可扩展集成
- **Claude Agent SDK / Managed Agents**：数据分析、Slack Bot、SRE 事件响应、生产部署与 prompt 版本回滚等端到端教程
- **多模态与进阶技巧**：Vision、图表解读、子代理组合、Prompt Caching、JSON Mode、内容审核过滤器
- **工程化配套**：`uv` + Makefile、`.env` 密钥模板、notebook 结构/执行测试，以及 Claude Code 校验命令

## 对用户价值

官方 API 文档讲清「能做什么」，Cookbooks 回答「怎么把概念跑通」。你可以直接打开对应 notebook，改密钥与输入数据，把工具调用、RAG、Agent 或评测流水线接到自己的项目里，减少从零拼胶水代码的时间。对团队而言，它是统一的 onboarding 与方案评审参考：先对照官方示例对齐实现路径，再决定是否引入 LangChain 等更重的编排框架。

## 与替代方案

- 相比 [Anthropic 开发者文档](https://docs.claude.com)，本仓库提供 **可执行 notebook 与端到端场景**，更偏动手实践，而非 API 参考手册。
- 相比 [LangChain](https://github.com/langchain-ai/langchain) / LlamaIndex 等 **应用编排框架**，Cookbooks 是 **官方原语层示例**；需要跨模型组件生态或复杂图编排时，再叠加框架。
- 相比社区 Claude Code 技巧库（如 Best Practice / Skills 合集），这里聚焦 **Claude API / Agent SDK / Managed Agents**，不是 CLI 工作流或 `.claude/` 配置策展。
- 概念较新时可先读 [Claude API Fundamentals 课程](https://github.com/anthropics/courses/tree/master/anthropic_api_fundamentals)，再进入本仓库按场景深入。

## 适应人群

- 已有 Anthropic API Key，想用官方可运行示例快速落地 RAG、工具调用或 Agent 的应用开发者。
- 评估 Managed Agents / Agent SDK 能否接入现有产品流程的后端与平台工程师。
- 需要在团队内统一「怎么用 Claude」示例与评测基线的 Tech Lead / AI 应用负责人。

## 如何使用

### 前置条件

- Python **3.11 或 3.12**（`pyproject.toml` 要求 `>=3.11,<3.13`）。
- 推荐安装 [uv](https://docs.astral.sh/uv/)；也可用 pip。
- 在 [Anthropic Console](https://console.anthropic.com/settings/keys) 申请 Claude API Key。
- 部分 third-party notebook 还需要 Pinecone、Voyage 等额外服务密钥。

### 安装方式

```bash
git clone https://github.com/anthropics/claude-cookbooks.git
cd claude-cookbooks

# 推荐：用 uv 同步依赖
uv sync --all-extras
# 或：make install

# 可选：安装 pre-commit
uv run pre-commit install

# 配置密钥
cp .env.example .env
# 编辑 .env，填入 ANTHROPIC_API_KEY
```

也可用 pip：`pip install -e ".[dev]"`。

### 首次运行

在 `registry.yaml` 中按类别挑选配方，或直接打开目录中的 notebook。例如：

```bash
uv run jupyter notebook
# 或
uv run jupyter lab
```

建议从较轻量示例入手（如 `tool_use/`、`capabilities/`），再进入 `managed_agents/`、`claude_agent_sdk/` 等进阶目录。测试时可将 `.env` 中的 `CLAUDE_MODEL` 设为较便宜的 Haiku 别名以控制成本。

### 验证是否成功

- Jupyter 能正常启动，且 notebook 内核为当前 `uv` 环境。
- 打开任一 notebook 后，`anthropic` 客户端能读取 `ANTHROPIC_API_KEY` 并成功完成一次 API 调用。
- 可选结构校验（无需完整跑通 API）：

```bash
make test-notebooks NOTEBOOK=tool_use/calculator_tool.ipynb
```

### 常见坑 / 注意事项

- **密钥勿入库**：只用 `.env` / 环境变量；仓库明确要求不提交 `.env`。
- **Python 版本**：暂不支持 3.13+；环境不对时 `uv sync` 会失败。
- **README 链接可能滞后**：部分目录链接仍指向旧路径名 `anthropic-cookbook`；以当前仓库目录与 `registry.yaml` 为准。
- **成本与模型别名**：完整执行 notebook 会消耗 API 额度；优先用文档推荐的非日期模型别名（如 `claude-haiku-4-5`），避免过时的 dated model ID。
- **第三方依赖**：Pinecone、Voyage、MongoDB 等示例需额外账号与配置，不是开箱即跑。
- Notebook **保留输出是刻意的**，用于展示预期结果；本地重跑前注意覆盖与费用。

---

# Mastodon

> 基于 ActivityPub 的自托管微博社区服务器，可联邦互联各实例用户。

- 页面：https://www.niceshare.site/github/mastodon/
- 仓库：https://github.com/mastodon/mastodon
- 官网：https://joinmastodon.org
- 语言：Ruby
- Stars：50045
- 许可证：AGPL-3.0
- 标签：自托管、后端、开发工具
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Mastodon 是一款基于 [ActivityPub](https://www.w3.org/TR/activitypub/) 协议的开源社交网络服务器，让你可以自建「实例（Instance）」并加入联邦宇宙（Fediverse）。用户可发布文字、链接、图片与视频，关注本实例或跨站点的账号；不同服务器之间可互相关注与互动，无需绑定单一商业平台。项目由 Mastodon GmbH 非营利组织维护，采用 AGPL-3.0 许可。

## 核心特性

- **联邦互联** — 基于开放标准 ActivityPub，与 Pixelfed、PeerTube、Lemmy 等实现互操作，无厂商锁定
- **实时时间线** — 关注对象的动态按时间顺序实时刷新，支持本地、联邦与公开时间线
- **富媒体与附件** — 支持图片、视频上传；无音轨视频可当作 GIF 循环播放
- **安全与 moderation** — 私密帖、锁定账号、关键词过滤、静音/屏蔽、举报与管理员审核工具
- **OAuth2 与 REST API** — 作为 OAuth2 提供方，第三方客户端可通过 REST 与 Streaming API 接入，生态应用丰富

## 对用户价值

中心化社交平台把社群、算法与数据锁在同一产品里，迁移成本高、规则也不透明。Mastodon 把「社区运营权」交还给实例管理员：你可以为团队、兴趣圈或地区用户搭建独立站点，同时通过联邦协议与全球用户互联。对个人用户，可在 [joinmastodon.org](https://joinmastodon.org/servers) 选择公共实例快速入门；对组织，自托管意味着合规、品牌与 moderation 策略完全自控，代价是需要承担运维、SMTP 与 moderation 人力。

## 与替代方案

- 相比 **Twitter / X、Threads**，Mastodon 无单一母公司控制全局时间线，实例可独立制定规则；但跨站体验依赖各实例 moderation 质量，搜索与推荐不如商业产品「开箱即用」。
- 相比 **Bluesky（AT Protocol）**，Mastodon 走 ActivityPub 联邦路线，生态更成熟、第三方客户端与实例数量更多；AT 协议在账号可移植性与协议设计上有不同取舍，两者目前并不直接互通。
- 相比 **Misskey、Pleroma、GoToSocial** 等 ActivityPub 实现，Mastodon 功能最完整、文档与 Docker 部署路径最主流，但资源占用更高；轻量个人节点可评估 GoToSocial 或 Pleroma。
- 相比 **Discord / Slack**，Mastodon 是公开/半公开微博形态，强项是广播式社交与联邦发现，而非频道式实时协作。

## 适应人群

- 希望为社群、公司或兴趣小组运营独立社交站，并保留数据与 moderation 自主权的系统管理员与社区运营者。
- 已有 VPS / Homelab，愿意维护 PostgreSQL、Redis、Sidekiq 与反向代理的后端或 DevOps 工程师。
- 需要 OAuth API 开发第三方客户端、Bot 或联邦集成工具的全栈开发者。

## 如何使用

### 前置条件

- **生产部署**：Linux 服务器（官方文档以 Ubuntu 24.04 / Debian 13 为例）、可解析的域名、可用的 SMTP 邮件服务（注册验证与通知必需）。
- **Docker 路径**：Docker 与 Docker Compose，以及 Nginx/Caddy 等反向代理处理 HTTPS。
- **源码路径**：Ruby 3.3+、PostgreSQL 14+、Redis 7.0+、Node.js 22+、FFmpeg 5.1+；详见 [系统要求](https://github.com/mastodon/mastodon#requirements)。
- 了解 AGPL-3.0：若修改代码并通过网络提供服务，需向用户提供对应源码。

### 安装方式

**Docker Compose（仓库内置配置，适合多数自托管场景）：**

```bash
git clone https://github.com/mastodon/mastodon.git live && cd live
git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1)
cp .env.production.sample .env.production
docker compose run --rm web bundle exec rake mastodon:setup
docker compose up -d
```

官方容器镜像：`ghcr.io/mastodon/mastodon`（稳定版如 `v4.6.0`）。`docker-compose.yml` 中请确认 PostgreSQL/Redis 数据卷已持久化，勿在生产环境使用默认 ephemeral 存储。

**从源码安装（Ubuntu/Debian 示例）：**

```bash
su - mastodon
git clone https://github.com/mastodon/mastodon.git live && cd live
git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1)
bundle config deployment 'true'
bundle config without 'development test'
bundle install && yarn install
RAILS_ENV=production bin/rails mastodon:setup
```

完整逐步说明见 [官方安装文档](https://docs.joinmastodon.org/admin/install/)。Kubernetes 用户可参考 [mastodon/chart](https://github.com/mastodon/chart)。

### 首次运行

- **Docker**：`mastodon:setup` 向导会生成 `.env.production`、创建数据库 schema 并预编译前端资源；完成后 `docker compose up -d` 启动 `web`、`streaming`、`sidekiq` 等服务。
- **源码**：向导结束后复制 `dist/nginx.conf` 与 `dist/mastodon-*.service` 到系统目录，配置 SSL（如 `certbot`），再 `systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming`。
- 浏览器访问你的域名，注册首个账号；首个注册用户通常自动成为管理员，可在「管理 → 站点设置」中完善实例名称、规则与注册策略。

### 验证是否成功

- 访问 `https://<你的域名>/health` 或首页，确认 Web 界面可加载且无 502。
- 发布一条测试嘟文，检查本地时间线与媒体附件是否正常。
- 在「管理 → 仪表盘」查看 Sidekiq 队列无持续积压；可选关注一个外部联邦账号，确认跨站互动可用。
- API 验证：`curl https://<你的域名>/api/v1/instance` 应返回实例元数据 JSON。

### 常见坑 / 注意事项

- **邮件未配置**：无法完成注册验证与密码重置，SMTP 是生产实例的硬性依赖。
- **`.env.production` 密钥**：`SECRET_KEY_BASE`、VAPID 密钥等一旦丢失或变更会导致会话失效；Docker 环境下注意引号转义（见 [issue #16895](https://github.com/mastodon/mastodon/issues/16895)）。
- **资源与 moderation**：Mastodon 栈含 PostgreSQL、Redis、Sidekiq、Streaming 与可选 Elasticsearch，小 VPS 易吃满内存；开放注册实例需投入 moderation，否则垃圾账号与联邦滥用会快速出现。
- **升级**：务必阅读 [Release Notes](https://github.com/mastodon/mastodon/releases)，Docker 环境通常 `docker compose pull` 后按说明执行 `db:migrate`；生产升级前备份数据库与 `public/system` 媒体目录。
- **只想使用而非运维**：不必自建，可在 [joinmastodon.org/servers](https://joinmastodon.org/servers) 挑选公共实例注册；自托管适合有明确社群或合规需求的团队。

---

# Last30Days Skill

> 跨 Reddit、X、YouTube、HN 等平台并行调研近 30 天热点的 Agent Skill，按真实互动量合成简报。

- 页面：https://www.niceshare.site/github/last30days-skill/
- 仓库：https://github.com/mvanhorn/last30days-skill
- 语言：Python
- Stars：49576
- 许可证：MIT
- 标签：Agent、工作流、AI 编程
- 收录：2026-07-06（更新于 2026-07-06）

## 项目介绍

Last30Days Skill 是一套面向 AI 编码助手的 **多源情报调研技能**，通过 `/last30days` 命令在 Reddit、X、YouTube、Hacker News、Polymarket、GitHub 等平台并行检索近 30 天内容，按点赞、评论、播放量与预测市场赔率等 **真实互动信号** 排序，再由 Agent 合成为带引用的中文或英文简报。v3 引擎新增实体解析（人名→X 账号/GitHub 用户）、跨源聚类合并、竞品对比与可分享的 HTML 简报，适合会议背调、工具选型与热点追踪等需要「社区共识」而非编辑精选的场景。

## 核心特性

- **多源并行检索**：Reddit（含评论）、HN、Polymarket、GitHub 零配置即用；X、YouTube、TikTok、Bluesky 等按需解锁 API 或浏览器会话
- **v3 实体预研大脑**：运行前解析话题对应的人、公司、子版块与话题标签，避免「Apple」误匹配汽车预测市场等噪音
- **互动量排序**：按 upvote、播放量、Polymarket 赔率与 GitHub star 等社区信号加权，而非 SEO 排名
- **跨源聚类与竞品模式**：同一故事在 Reddit/X/YouTube 合并展示；`--competitors` 自动发现同行并做并行对比
- **可分享 HTML 简报**：`--emit=html` 或自然语言请求，输出离线可用的深色主题简报至 `~/Documents/Last30Days/`
- **多宿主安装**：Claude Code 插件市场、Agent Skills CLI（Cursor/Codex/Copilot 等 50+ 宿主）、claude.ai 上传、OpenClaw 与 Claude Desktop MCP

## 对用户价值

Google 与通用大模型各自只能触及部分平台，且训练数据往往滞后于社区讨论。Last30Days 把分散在 Reddit 热评、X 线程、YouTube 字幕与预测市场赔率中的信号桥接起来，一次命令即可得到「过去 30 天人们真正在讨论什么」的浓缩视图。对个人，它把原本逐站翻帖的 90 分钟调研压缩到几分钟；对团队，HTML 简报可直接丢进 Slack 或邮件，作为会前背调、竞品评估与选题研究的共同事实基础。

## 与替代方案

- 相比 **Perplexity / 通用 Web Search**，本技能更侧重 **社交平台原始互动数据**（Reddit 评论 upvote、X 热度、YouTube 字幕、Polymarket 赔率），而非单一搜索引擎摘要；Perplexity 可作为可选补充源（需 `PERPLEXITY_API_KEY`）。
- 相比 **手动逐站搜索**，提供实体解析、跨源去重、每作者上限（最多 3 条）与 1,012 项测试覆盖的 **可重复流水线**，并支持 `--store` + watchlist 做趋势监控。
- 相比 [Agent Skills](https://github.com/addyosmani/agent-skills) 等 **工程交付类技能**，本仓库专注 **外部情报调研**，不替代规格驱动开发或代码审查流程。
- 全量多源需自备 API Key 或浏览器 Cookie；**不是**零成本的万能搜索，未配置时自动降级为 Reddit/HN/Polymarket/GitHub 等免费源。

## 适应人群

- 会议、销售拜访或投资人沟通前，需要快速掌握某人/某公司近 30 天公开动态的从业者。
- 评估 OpenClaw vs Hermes 等工具选型、或追踪 AI 热点时，希望看到社区讨论而非过时博客的开发者。
- 已在用 Claude Code、Cursor 或 Codex，想把多平台调研嵌入 Agent 工作流的知识工作者。

## 如何使用

### 前置条件

- Python 3.12+（Claude Desktop MCP 与 CLI 引擎均依赖本地解释器）。
- 任选 README 列出的 Agent 宿主（Claude Code 为推荐路径，支持 marketplace 自动更新）。
- Reddit、HN、Polymarket、GitHub **无需密钥**即可起步；X、YouTube、TikTok 等扩展源需按 README 配置 Cookie 或 API Key。

### 安装方式

**Claude Code（推荐，自动更新）**

```
/plugin marketplace add mvanhorn/last30days-skill
/plugin install last30days
```

**Cursor、Codex、Copilot、Gemini CLI 等 Agent Skills 宿主**

```bash
npx skills add mvanhorn/last30days-skill -g
```

`-g` 全局安装，跨项目可用；仅当前仓库则省略 `-g`。指定宿主示例：

```bash
npx skills add mvanhorn/last30days-skill -g -a cursor
npx skills add mvanhorn/last30days-skill -g -a codex
```

更新：

```bash
npx skills update last30days -g
```

**claude.ai 网页版**：从 [Releases](https://github.com/mvanhorn/last30days-skill/releases/latest/download/last30days.skill) 下载 `.skill` 文件，在 Customize → Skills 中上传；需先开启「Code execution and file creation」能力。

### 首次运行

安装后在对话中输入调研命令，例如：

```
/last30days Peter Steinberger
/last30days OpenClaw vs Hermes --competitors
/last30days Cursor IDE --emit=html
```

首次执行会触发 **30 秒设置向导**，引导解锁 X、YouTube 等扩展源。也可在源码目录预检配置（不读 Cookie、不写文件）：

```bash
python3 skills/last30days/scripts/last30days.py --preflight
```

### 验证是否成功

确认 `/last30days` 或等价命令被宿主识别；对简单话题（如公开人物或热门开源项目）应返回带多源引用的合成简报，而非「请查阅 README」。若请求 HTML，检查 `~/Documents/Last30Days/{topic}-brief.html` 是否生成且可离线打开。引擎 stderr 中的降级提示属正常行为，不会写入分享文件。

### 常见坑 / 注意事项

- Claude Code 上 **marketplace 插件与 `npx skills` 安装可并存**，但会显示两个 `/last30days` 入口；建议每台机器只选一种安装方式。
- Claude Desktop 与 Claude Code 的 **凭据存储相互独立**；在 `~/.config/last30days/.env` 配过的 Key 需在 Desktop 侧重新录入。
- ScrapeCreators、Perplexity 等为 **按量付费** API；`INCLUDE_SOURCES=perplexity` 等 opt-in 开关用于避免意外扣费。
- 项目声明 **无官方代币**；任何借用项目名称的加密资产均未获背书。
- v3 仍在快速迭代，关键决策前建议人工核对引用原文；升级前阅读 [CHANGELOG](https://github.com/mvanhorn/last30days-skill/blob/main/CHANGELOG.md)。

---

# Aider

> 在终端里与大模型结对编程的开源 CLI，支持代码库地图与 Git diff 审查。

- 页面：https://www.niceshare.site/github/aider/
- 仓库：https://github.com/Aider-AI/aider
- 官网：https://aider.chat/
- 语言：Python
- Stars：46474
- 许可证：Apache-2.0
- 标签：AI 编程、CLI、开发工具
- 收录：2026-06-19（更新于 2026-06-19）

## 项目介绍

Aider 是终端里的 AI 结对编程工具，可读取代码库上下文、生成补丁并配合 Git 工作流迭代。它适合习惯命令行、希望保留清晰 diff 审查节奏的开发者，也支持云端与本地多种大模型。

## 核心特性

- 自动构建代码库地图，在大项目中保持上下文相关
- 直接编辑文件并展示 Git diff，便于逐轮审查
- 支持 100+ 编程语言与主流 LLM（Claude、GPT、DeepSeek、本地模型等）
- 可与现有 Git 分支、提交习惯无缝配合
- 提供安装向导、教程与丰富的配置选项

## 对用户价值

Aider 的价值在于低摩擦：开发者在当前仓库直接提出修改目标，查看模型生成的变更，再决定是否接受。它把对话、文件编辑和 Git 反馈环放在一个终端流程里，比来回复制粘贴到 Web 聊天更高效。

## 与替代方案

- 相比 IDE 内嵌助手（Continue、Copilot），Aider 更贴近终端与 Git 原生工作流。
- 相比 Cline 等自主代理，Aider 更强调人机结对与逐 diff 确认，自主性较低但更可控。
- 若团队需要图形化 Kanban 或多代理并行，可评估 Cline 等方案。

## 适应人群

- 偏好终端和 Git 工作流的开发者。
- 想用 AI 辅助局部重构、测试和文档的人。
- 需要快速比较不同模型编码能力的技术用户。

## 如何使用

### 前置条件

- Python 3.8+ 环境。
- 目标项目为 Git 仓库（建议先提交或创建干净分支）。
- 所用模型的 API 密钥或本地端点。

### 安装方式

```bash
python -m pip install -U aider-chat
```

或使用官方安装脚本 `aider-install`（见 [安装文档](https://aider.chat/docs/install.html)）。

### 首次运行

```bash
cd your-repo
aider
```

按提示配置模型提供方，可用 `/add` 指定要编辑的文件，再描述修改目标。

### 验证是否成功

让 Aider 完成一个小改动（如补充注释或单测），检查 `git diff` 是否符合预期并能正常提交。

### 常见坑 / 注意事项

- 大仓库建议从小范围文件集开始，避免上下文过长或成本失控。
- 自动提交前务必审查 diff，敏感目录可用 `.aiderignore` 排除。
- 本地模型需确认 Aider 支持的 API 格式与上下文窗口。

---

# zx

> Google 出品的 JavaScript Shell 脚本工具，跨平台封装子进程调用、自动转义参数，用 `$` 模板语法替代复杂 Bash。

- 页面：https://www.niceshare.site/github/zx/
- 仓库：https://github.com/google/zx
- 官网：https://google.github.io/zx/
- 语言：JavaScript
- Stars：45549
- 许可证：Apache-2.0
- 标签：CLI、开发工具、自动化
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

[zx](https://google.github.io/zx/) 是 Google 开源的 JavaScript Shell 脚本工具，目标是在保留 Shell 执行能力的同时，用 JavaScript 的语法与生态替代难以维护的 Bash 脚本。它围绕 `child_process` 提供跨平台封装，自动转义参数、给出合理默认值，并通过 `$` 模板标签让命令调用接近原生 Shell 写法。项目支持 Node.js、Bun、Deno 等多种运行时，适用于 CI 流水线、发布脚本与本地自动化任务。

## 核心特性

- **`$` 模板语法**：用 `` await $`git branch --show-current` `` 执行命令，支持变量插值与管道，写法接近 Bash 但具备 JavaScript 控制力
- **跨平台 child_process 封装**：统一处理参数转义、stdout/stderr 捕获与退出码，减少 Windows / macOS / Linux 差异带来的脚本分支
- **异步与并行**：原生 `async/await` 与 `Promise.all` 并行执行多条命令，适合部署、构建等多步骤流水线
- **多运行时与模块格式**：兼容 Node.js ≥ 12.17、Bun、Deno、GraalVM；同时提供 CJS 与 ESM 入口，支持 TypeScript
- **多种安装渠道**：npm 包、全局 CLI、`npx` 零安装运行、Homebrew、Docker 镜像，以及轻量版 `zx@lite`

## 对用户价值

当你需要把「几行 Bash」扩展成带条件分支、错误处理、HTTP 请求或 JSON 解析的自动化脚本时，zx 让你留在 JavaScript 生态内完成，而不必在 Bash 与 Node 之间来回切换。CI 配置、发布脚本、代码生成器、本地开发工具链都能受益：团队若已熟悉 JS/TS，维护成本低于纯 Shell；相比手写 `child_process`，zx 处理了转义、默认 shell 与常见边界情况。代价是需要 Node（或 Bun/Deno）运行时，且极简单的单行命令仍可能直接用 Bash 更轻。

## 与替代方案

- 相比 **原生 Bash / sh**，zx 更适合复杂逻辑、结构化数据处理与 npm 生态集成；纯文件操作或系统级 one-liner 仍可能 Bash 更直接。
- 相比 **[execa](https://github.com/sindresorhus/execa)**，zx 提供 `$` 语法糖、全局 CLI 与文档化的脚本工作流；execa 更偏库级 API，适合嵌入应用而非独立脚本文件。
- 相比 **[shelljs](https://github.com/shelljs/shelljs)**，zx 基于现代异步模型与 Promise，API 与维护节奏更贴近当前 Node 生态；shelljs 偏同步、历史包袱较多。
- 相比 **Python [Invoke](https://www.pyinvoke.org/) / Fabric**，zx 复用前端与 Node 团队已有技能栈；Python 方案在数据科学与运维 Ansible 场景可能更自然。
- 边界说明：非 Google 官方支持产品；Windows 需 WSL、Git Bash 或切换 `usePowerShell()` / `usePwsh()`。

## 适应人群

- 维护 CI/CD、发布脚本或 monorepo 工具链，希望用 JavaScript 统一自动化逻辑的前端与 DevOps 工程师。
- 已熟悉 Node.js，想把复杂 Bash 脚本迁移为可读、可测试的 JS/TS 脚本的个人开发者与小团队。
- 需要在脚本中并行调用 CLI、处理 Git 分支/部署参数，并追求跨平台一致行为的效率型用户。

## 如何使用

### 前置条件

- 操作系统：Linux、macOS 或 Windows（Windows 建议 WSL、Git Bash，或配置 PowerShell）。
- JavaScript 运行时（任选其一）：Node.js ≥ 12.17.0、Bun ≥ 1.0.0、Deno 1.x/2.x，或 GraalVM Node.js。
- 系统需可用 bash 或 PowerShell（zx 默认查找 bash，可通过 API 切换 shell）。

### 安装方式

**方式一：项目依赖（推荐）**

```bash
npm install zx
# 或
pnpm add zx
yarn add zx
bun install zx
```

**方式二：零安装运行**

```bash
npx zx script.mjs
npx zx@8.6.0 script.mjs   # 锁定版本
```

**方式三：全局 CLI**

```bash
npm install -g zx
# 或 macOS
brew install zx
```

**轻量版**（功能精简、体积更小）：`npm install zx@lite`

更多渠道见 [Setup 文档](https://google.github.io/zx/setup)（Docker、Deno JSR、GitHub pkg registry 等）。

### 首次运行

创建脚本文件并添加 shebang，在文件顶部导入 `$`：

```js
#!/usr/bin/env zx

await $`cat package.json | grep name`

const branch = await $`git branch --show-current`
await $`echo deploying branch: ${branch}`
```

赋予执行权限后直接运行：

```bash
chmod +x deploy.mjs
./deploy.mjs
```

或通过 CLI：

```bash
zx deploy.mjs
```

TypeScript 用法与类型定义见 [官方 TS 文档](https://google.github.io/zx/typescript)；示例集合见 [examples/](https://github.com/google/zx/tree/main/examples)。

### 验证是否成功

```bash
# 快速验证安装
npx zx -e="console.log(await \$`echo hello`.stdout.trim())"
# 期望输出: hello
```

或在项目中：

```bash
node -e "import('$').then(async ({ $ }) => console.log((await \$`echo ok`).stdout.trim()))"
```

确认命令 stdout 符合预期、非零退出码时脚本能按预期抛出或处理即可。

### 常见坑 / 注意事项

- **Windows shell**：默认依赖 bash；纯 PowerShell 环境需调用 `usePowerShell()` 或 `usePwsh()`，否则可能找不到 shell。
- **TypeScript 类型**：使用 TS 时需额外安装 `@types/node` 与 `@types/fs-extra`（见 Setup 文档）。
- **版本渠道**：`latest` / `lite` / `dev` / `legacy` 功能集不同，生产脚本建议锁定主版本（如 `npx zx@8.x`）。
- **安全**：脚本内勿硬编码密钥；`$` 会执行真实 shell 命令，对用户输入做转义或校验后再插值。
- **免责声明**：Apache-2.0 许可，但 README 标明非 Google 官方支持产品，企业采纳前请自行评估 SLA 与维护风险。

---

# RSSHub

> 开源 RSS 路由生成器，为 B 站、微博、Twitter 等数千平台提供统一 RSS 订阅输出。

- 页面：https://www.niceshare.site/github/rsshub/
- 仓库：https://github.com/DIYgod/RSSHub
- 官网：https://docs.rsshub.app
- 语言：TypeScript
- Stars：45000
- 许可证：AGPL-3.0
- 标签：自动化、开发工具、知识管理
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

RSSHub 是全球规模最大的开源 RSS 路由网络之一， slogan 是「Everything is RSSible」。它为 B 站、微博、Twitter、Telegram 等原本不提供 RSS 的平台编写抓取路由，输出标准 RSS/Atom 订阅源，方便接入 Folo、FreshRSS、Miniflux 等阅读器。项目采用 AGPL-3.0 许可，拥有 1300+ 贡献者与数千个预置路由，既可使用公共实例，也支持 Docker 或 Node.js 自托管。

## 核心特性

- 数千条预置路由，覆盖社交媒体、新闻、视频、学术等常见信息源
- 标准 RSS/Atom 输出，兼容主流 RSS 阅读器与自动化工具
- 支持内容过滤、全文输出等 URL 参数，可按需定制订阅内容
- Radar 规则与 RSSHub Radar 浏览器扩展，可快速发现当前网站的 RSS 地址
- 提供 npm 包，可在 Node.js 项目中以 API 方式调用路由
- Docker Compose 一键部署，可选 bundled Chromium 以支持需 Puppeteer 的路由

## 对用户价值

许多平台不再提供官方 RSS，RSSHub 把「找源 → 写爬虫 → 维护格式」封装成统一路由。用户只需按文档拼出 URL（如 `https://rsshub.app/telegram/channel/awesomeRSSHub`），即可在阅读器里集中追踪分散在各 App 里的更新，减少手动刷信息流的时间成本。

## 与替代方案

- 相比 Feed43、FeedBurner 等在线转制服务，RSSHub 开源可自托管，路由社区维护、覆盖面更广。
- 相比 Huginn、n8n 等通用自动化平台，RSSHub 专注 RSS 输出，路由即用、对阅读器场景更直接。
- 相比为每个站点单独写爬虫，RSSHub 提供统一协议与共享路由，但复杂站点仍可能因反爬或页面改版而失效，需关注路由状态或自行维护 fork。

## 适应人群

- 依赖 RSS 追踪资讯、社交动态或 UP 主更新的重度阅读者。
- 希望自托管订阅基础设施、控制数据与访问频率的技术用户。
- 需要把多平台内容汇聚到 Folo、FreshRSS 等工作流的开发者与运营者。

## 如何使用

### 前置条件

- 使用公共实例时：任意 RSS 阅读器即可，无需本地环境。
- 自托管时：Docker 与 Docker Compose（推荐），或 Node.js 与 pnpm；部分路由需 Redis 缓存或 Chromium/Puppeteer 依赖。

### 安装方式

Docker Compose（推荐）：

```bash
wget https://raw.githubusercontent.com/DIYgod/RSSHub/master/docker-compose.yml
docker-compose up -d
```

或单容器快速体验：

```bash
docker run -d --name rsshub -p 1200:1200 diygod/rsshub
```

手动部署：

```bash
git clone https://github.com/DIYgod/RSSHub.git
cd RSSHub
pnpm i
pnpm build
pnpm start
```

### 首次运行

浏览器访问 `http://localhost:1200`（自托管）或查阅 [路由文档](https://docs.rsshub.app/) 找到目标平台路径。将实例域名与路由拼接成完整 URL，例如 Telegram 频道 `@awesomeRSSHub` 对应 `/telegram/channel/awesomeRSSHub`，加入阅读器订阅列表。

### 验证是否成功

在阅读器中确认新订阅能拉取到条目；若路由需参数，对照文档检查 username、ID 等占位符是否填写正确。自托管实例可访问 `/api/radar/rules` 查看当前支持的 Radar 规则。

### 常见坑 / 注意事项

- 公共实例 `rsshub.app` 有访问频率限制，高频或生产用途建议自托管。
- 无 Chromium 的镜像不支持依赖 Puppeteer 的路由，需使用 `diygod/rsshub:chromium-bundled` 或 Docker Compose 完整栈。
- 部分源会因目标站反爬、登录或页面改版而失效，可查阅 GitHub Issues 或社区 Telegram 获取路由状态。
- AGPL-3.0 对网络服务部署有传染性要求，商业场景部署前请阅读许可证条款。

---

# Sentry

> 面向开发者的错误追踪与性能监控平台，聚合线上异常、链路追踪与告警，加速定位与修复。

- 页面：https://www.niceshare.site/github/sentry/
- 仓库：https://github.com/getsentry/sentry
- 官网：https://sentry.io
- 语言：Python
- Stars：44136
- 许可证：FSL
- 标签：开发工具、后端、自动化
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Sentry 是面向开发者的调试与可观测性平台，帮助团队检测、追踪并修复线上问题。本仓库（`getsentry/sentry`）是 Sentry 服务端核心源码，基于 Python/Django 构建，涵盖错误监控、分布式追踪、性能剖析、日志与指标等能力。多数团队通过官方 SaaS（sentry.io）或自托管（`getsentry/self-hosted`）接入，再在应用里嵌入对应语言的官方 SDK，将异常与性能数据上报到统一控制台。

## 核心特性

- **错误监控（Issues）**：自动捕获未处理异常、Promise rejection 与自定义消息，附带堆栈、面包屑与用户上下文
- **分布式追踪（Tracing）**：跨前端、API 与微服务关联请求链路，定位慢调用与级联故障
- **性能剖析（Profiling）**：无需大量手工埋点即可发现 CPU/内存热点函数
- **日志与指标**：将应用日志、自定义 metrics 与错误/性能事件关联，便于统一检索与告警
- **多语言 SDK 生态**：官方维护 JavaScript、Python、Go、Java、Rust、Mobile 等 20+ 平台 SDK，框架集成（Django、FastAPI、React 等）开箱即用
- **Release 与告警**：按版本对比错误率，对接 Slack、PagerDuty 等通知渠道，支持 Cron 监控与 Feature Flag 上下文

## 对用户价值

生产环境仅靠日志往往难以还原用户侧异常，更无法把前端报错与后端慢查询串成一条链路。Sentry 把「捕获—聚合—分派—回归验证」收敛到单一平台：开发者在代码里几行 SDK 初始化即可上线监控，On-call 工程师在 Issue 详情页直接看到堆栈、Release 差异与受影响用户数，显著缩短 MTTR。对需要数据驻留或内网合规的团队，Fair Source 许可下的自托管方案提供了与 SaaS 接近的功能面（Billing、部分 AI 能力等除外）。

## 与替代方案

- 相比 **Rollbar / Bugsnag**，Sentry 在分布式追踪、性能剖析与开源自托管上更完整，社区与 SDK 覆盖面更广；后两者更轻量，适合仅需基础错误通知的小项目。
- 相比 **Datadog / New Relic**，Sentry 以开发者工作流为中心（Issue 分组、Release 对比、源码上下文），APM 深度略逊但上手更快、定价对中小团队更友好；若已全面使用 Datadog 且需要统一基础设施监控，可优先评估其 Error Tracking 模块。
- 相比 **GlitchTip**（开源 Error Tracking），Sentry 功能栈更全（Tracing、Profiling、Crons 等）且生态成熟，但自托管资源占用更高、许可为 FSL 而非传统 OSI 开源。
- **边界说明**：`getsentry/sentry` 是服务端源码；实际自托管部署应使用 [`getsentry/self-hosted`](https://github.com/getsentry/self-hosted) 的 Docker Compose 方案。许可为 **FSL（Functional Source License）**：可自由部署与使用，但不得将自托管实例作为 SaaS 对外售卖，亦不得作为 Sentry 直接竞争对手使用其 FSL 代码；约 2 年后转为 Apache 2.0。

## 适应人群

- 维护 Web、Mobile 或 API 服务，需要统一捕获线上异常并关联 Release 的全栈与后端工程师。
- 负责 On-call 与 SLA 的 SRE / DevOps 团队，希望用告警、Issue 归属与性能追踪降低故障恢复时间。
- 有数据合规或内网部署要求，愿意承担 Docker 集群运维成本、评估 FSL 许可边界的工程组织。

## 如何使用

### 前置条件

**SDK 接入（最常见路径）：**

- 拥有 Sentry 账号与项目（[sentry.io](https://sentry.io) 注册，或使用已部署的自托管实例）。
- 应用运行时与对应官方 SDK 兼容（如 Python 3.8+、Node.js 等，见 [平台文档](https://docs.sentry.io/platforms/)）。

**自托管部署：**

- 服务器：至少 4 核 CPU、16 GB RAM + 16 GB swap、20 GB 磁盘（官方建议 32 GB RAM）。
- Docker ≥ 19.03.6，Docker Compose ≥ 2.32.2。
- 推荐 Debian/Ubuntu；RHEL 系需额外处理 SELinux，Alpine 不受支持。

### 安装方式

**方式一：在应用中安装 SDK（以 Python 为例）：**

```bash
pip install "sentry-sdk"
```

其他语言见 [官方 SDK 列表](https://github.com/getsentry/sentry#official-sentry-sdks) 或 [docs.sentry.io/platforms](https://docs.sentry.io/platforms/)。

**方式二：自托管 Sentry 服务端：**

```bash
VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/getsentry/self-hosted/releases/latest)
VERSION=${VERSION##*/}
git clone https://github.com/getsentry/self-hosted.git
cd self-hosted
git checkout ${VERSION}
./install.sh
docker compose up --wait
```

默认 Web 界面绑定 `9000` 端口。完整说明见 [Self-Hosted Sentry 文档](https://develop.sentry.dev/self-hosted/)。

### 首次运行

**SDK 接入：** 在应用入口尽早初始化 SDK（DSN 取自 Sentry 项目设置页）：

```python
import sentry_sdk

sentry_sdk.init(
    dsn="https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
    send_default_pii=True,
    traces_sample_rate=1.0,  # 生产环境请按流量调低采样率
)
```

**自托管：** `./install.sh` 完成后执行 `docker compose up --wait`，浏览器访问 `http://127.0.0.1:9000` 创建管理员账号，再在控制台新建 Organization / Project 获取 DSN。

### 验证是否成功

**SDK：**

```python
division_by_zero = 1 / 0
```

运行后等待数秒，在 Sentry 项目 **Issues** 页应出现对应错误事件；Tracing 可手动创建 transaction 验证 **Traces** 页是否有数据。

**自托管：**

- 访问 `http://127.0.0.1:9000` 能正常登录。
- 负载均衡/反向代理场景下，对 `/_health/` 端点做 HTTP 健康检查应返回 200。
- 将测试 SDK 的 DSN 指向自托管实例域名，确认事件能写入本地项目。

### 常见坑 / 注意事项

- **采样率**：`traces_sample_rate=1.0` 仅适合开发/验证；生产高流量场景务必调低，否则成本与存储压力激增。
- **自托管资源**：Sentry 单机 Docker 栈含 Kafka、ClickHouse 等组件，磁盘 I/O 敏感；`iowait > 10%` 通常表示机器扛不住负载，需扩容或迁外部对象存储（S3/GCS）。
- **许可合规**：FSL 禁止将自托管 Sentry 作为对外 SaaS 售卖，闭源竞品使用 FSL 代码亦受限；商用前请阅读 [Licensing](https://develop.sentry.dev/self-hosted/#licensing) 说明。
- **功能差异**：自托管不含 Billing 配额、Spike Protection、Seer 等 AI 能力；iOS 符号化、部分游戏平台支持亦受限于闭源组件或合作伙伴协议。
- **生产化**：公网暴露前应在负载均衡后配置 TLS，并同步修改 `config.yml` 的 `system.url-prefix` 与 `sentry.conf.py` 中的 SSL/CSRF 相关设置，否则集成 OAuth 等操作可能报 CSRF 错误。

---

# Free Claude Code

> 本地代理网关：用自选免费/付费/本地模型驱动 Claude Code、Codex、Pi 及其 IDE 扩展。

- 页面：https://www.niceshare.site/github/free-claude-code/
- 仓库：https://github.com/Alishahryar1/free-claude-code
- 语言：Python
- Stars：43865
- 许可证：MIT
- 标签：AI 编程、开发工具、Agent
- 收录：2026-08-03（更新于 2026-08-03）

## 项目介绍

Free Claude Code（FCC）是一个本地运行的供应商代理：把 Claude Code、Codex、Pi 及其 IDE 扩展接到你自己配置的云端或本地模型上。通过本机 Admin UI 选择、校验并应用供应商，用 `fcc-claude` / `fcc-codex` / `fcc-pi` 启动客户端，即可在免费档、付费 API 与 Ollama / LM Studio 等本地模型之间切换，同时尽量保留流式输出、工具调用、推理与图像输入等能力。

## 核心特性

- **一键启动器**：`fcc-claude`、`fcc-codex`、`fcc-pi` 按当前 Admin 配置拉起对应编码 Agent
- **多供应商 Admin UI**：在约 31 家云端与本地供应商间切换并 Validate / Apply（NVIDIA NIM、OpenRouter、Gemini、DeepSeek、Bedrock、Ollama 等）
- **原生模型选择器**：代理暴露网关模型目录，可在 Claude Code / Codex 自带的 `/model` 选择器中挑选
- **分级路由**：可为 Fable / Opus / Sonnet / Haiku 分别指定模型，其余请求走默认 `MODEL` 回退
- **桌面与扩展集成**：Windows / macOS 托盘或菜单栏后台运行；支持 VS Code、JetBrains ACP，以及可选的 Discord / Telegram（含语音转录）

## 对用户价值

官方 Claude Code / Codex 往往绑定特定订阅或账号体系；若你已有 NVIDIA NIM、OpenRouter 免费档、ChatGPT 订阅、本地 Ollama 等资源，却无法直接喂给这些 Agent，FCC 把「改 Base URL + 统一鉴权 + 模型目录」收成可操作的本地网关。对个人开发者，它降低多供应商试错成本；对习惯终端与 IDE 双开的用户，同一套 Admin 配置可同时服务 CLI 与扩展。可选消息与语音集成则适合希望在手机或聊天工具侧继续会话的场景。

## 与替代方案

- 相比直接使用 **Anthropic / OpenAI 官方登录**：FCC 侧重「自带供应商密钥或本地模型」；若你只用单一官方订阅且不换模型，官方路径更简单。
- 相比 **[OmniRoute](https://github.com/diegosouzapw/OmniRoute)** 等通用 AI 网关：OmniRoute 更强调跨多工具的免费档聚合与配额回退；FCC 更贴 Claude Code / Codex / Pi 的启动器、原生模型选择器与分级路由。
- 相比 **[CC Switch](https://github.com/farion1231/cc-switch)**：CC Switch 是配置与供应商切换桌面层；FCC 是常驻本地代理进程，负责协议翻译与请求转发。二者可互补：前者管配置，后者跑流量。
- 边界：各上游免费额度、ToS 与模型对工具调用的支持差异很大；本地小模型若上下文不足，Agent 体验会明显下降。

## 适应人群

- 已安装 Claude Code / Codex / Pi，希望改用 NIM、OpenRouter、Gemini、本地 Ollama 等供应商的开发者。
- 需要在多个模型间做 Opus/Sonnet/Haiku 分级路由，或在 IDE 与终端共用同一本地代理的用户。
- 想通过 Discord / Telegram（可选语音）远程驱动 Claude Code 会话的效率型玩家。

## 如何使用

### 前置条件

- 能运行安装脚本的环境（macOS / Linux / Windows PowerShell）；安装器会处理 Python / uv 等依赖。
- 至少准备一种供应商密钥或本地推理服务（README 默认示例为 NVIDIA NIM），并了解各上游服务条款。
- 建议先安装或允许安装器校验 Claude Code、Codex、Pi 中至少一种客户端。

### 安装方式

**macOS / Linux：**

```bash
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh
```

**Windows PowerShell：**

```powershell
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1")))
```

安装过程会询问要安装或校验哪些编码 Agent；至少选一种。同一命令可重复执行以更新。安装脚本可先在仓库中审阅再运行。

### 首次运行

1. **启动 FCC**：Windows / macOS 打开桌面或开始菜单中的 **Free Claude Code**（托盘 / 菜单栏后台）；Linux 运行 `fcc-server`，保持终端打开。
2. 查看启动日志中的 Admin UI 地址（默认类似 `http://127.0.0.1:8082/admin`，以实际端口为准）。
3. 在 Admin UI 配置供应商（例如粘贴 `NVIDIA_NIM_API_KEY`，选择 `MODEL`）→ **Validate** → **Apply**。
4. 启动客户端：

```bash
fcc-claude
# 或
fcc-codex
# 或
fcc-pi
```

可用 Agent 自带的模型选择器切换 FCC 暴露的模型；普通 CLI 参数仍可用，例如 `fcc-codex exec "hello"`。

### 验证是否成功

- `fcc-server --version` 能打印版本；Admin UI 可打开且 Validate 通过。
- `fcc-claude` / `fcc-codex` / `fcc-pi` 能启动，并在模型选择器中看到 FCC 网关模型。
- 发起一次简单对话或 `exec`，确认流式回复正常、无鉴权或端口错误。

### 常见坑 / 注意事项

- **端口与 Token 不一致**：IDE / Codex 配置中的 `base_url`、Bearer Token 必须与 Admin UI 一致（文档示例常为 `8082` 与 `freecc`）。
- **Claude Code 仍要求登录**：可向 `~/.claude.json`（Windows 为 `%USERPROFILE%\.claude.json`）合并 `"hasCompletedOnboarding": true` 后重启客户端。
- **优先选支持工具调用的模型**：编码 Agent 依赖 tools；本地模型还需足够上下文容纳系统提示与工具定义。
- **OpenAI / ChatGPT**：走 Admin「Providers → Connected accounts」连接订阅，而非普通 API Key；连接后需重启已运行的 Agent 以刷新模型列表。
- **安全**：可选开启本地代理 Token 鉴权；密钥保存在本机配置中，勿提交到仓库。卸载前先停掉所有 FCC 进程，再运行官方 uninstall 脚本（会删除 `~/.fcc/`，但保留 Claude Code / Codex / Pi 本体）。

---

# Logseq

> 隐私优先的开源知识管理与协作平台，支持本地优先的双链笔记。

- 页面：https://www.niceshare.site/github/logseq/
- 仓库：https://github.com/logseq/logseq
- 官网：https://logseq.com
- 语言：Clojure
- Stars：43457
- 许可证：AGPL-3.0
- 标签：知识管理、本地优先、开发工具
- 收录：2026-06-19（更新于 2026-06-19）

## 项目介绍

Logseq 是隐私优先、开源的知识管理平台，围绕本地文件、双向链接和大纲式写作组织知识。它不直接属于 AI 工具，但对开发者的长期学习、研究和项目记录很有帮助，并支持插件扩展与团队协作场景。

## 核心特性

- 大纲式双链笔记，页面与块级引用灵活
- 本地优先，数据以 Markdown 等格式存储在用户设备
- 支持日记、任务、PDF 批注与查询
- 插件 API 与活跃社区生态
- 提供桌面端与 Web 测试版，支持 DB 图（新版本数据模型）

## 对用户价值

Logseq 适合沉淀「可连接」的知识，而不是只保存孤立文档。开发者可以用它记录问题、方案、阅读笔记和项目日志，通过链接与查询逐步形成可检索、可回顾的个人知识系统。

## 与替代方案

- 相比 Obsidian，Logseq 默认大纲驱动、日记中心更强，界面哲学不同。
- 相比 Notion 等云端协作，Logseq 更强调本地文件与隐私控制。
- 若团队需要强实时协同编辑，应评估 Notion、飞书文档等云端方案。

## 适应人群

- 重视本地数据和 Markdown 文件的知识管理用户。
- 需要整理研究、学习和项目笔记的开发者。
- 想研究 local-first 应用形态的产品和工程团队。

## 如何使用

### 前置条件

- macOS / Windows / Linux 桌面环境，或现代浏览器（Web 版）。
- 了解 AGPL-3.0 许可对衍生与网络部署的要求。

### 安装方式

从 [GitHub Releases](https://github.com/logseq/logseq/releases) 或 [logseq.com](https://logseq.com) 下载对应平台安装包。

### 首次运行

创建或打开一个 graph，从每日笔记开始记录，尝试用 `[[页面链接]]` 与 `#标签` 组织内容。

### 验证是否成功

创建几条互链笔记并使用查询（如 `{{query [[某主题]]}}`），确认链接与搜索正常工作。

### 常见坑 / 注意事项

- 团队同步需自行规划（Git、Syncthing 或官方同步方案），备份策略要提前定好。
- DB 版与文件版数据模型不同，迁移前阅读官方说明。
- 插件质量参差，生产环境谨慎启用第三方扩展。

---

# pm2

> Node.js 生产级进程管理器，守护应用常驻、集群负载均衡与零停机热重载。

- 页面：https://www.niceshare.site/github/pm2/
- 仓库：https://github.com/Unitech/pm2
- 官网：https://pm2.keymetrics.io/docs/usage/quick-start/
- 语言：JavaScript
- Stars：43223
- 许可证：AGPL-3.0
- 标签：开发工具、自动化、CLI
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

PM2（Process Manager 2）是面向 Node.js 与 Bun 应用的生产级进程管理器，自 2013 年起广泛用于线上部署。它把应用以守护进程方式常驻运行，崩溃后自动拉起，并提供集群模式在多核机器上负载均衡 HTTP/TCP/UDP 流量。配合 `pm2 reload` 可实现零停机热更新，同时覆盖日志聚合、开机自启脚本生成、Docker `pm2-runtime` 集成等常见运维任务，支持 Linux、macOS 与 Windows。

## 核心特性

- **一键守护启动**：`pm2 start app.js` 将应用后台化，持续监控并在异常退出时自动重启
- **集群与负载均衡**：`pm2 start api.js -i max` 按 CPU 核数启动多实例，显著提升多核吞吐与容错能力
- **零停机热重载**：`pm2 reload all` 滚动更新进程，避免发布时中断在线请求
- **日志与监控**：`pm2 logs`、`pm2 monit` 集中查看输出；可安装 `pm2-logrotate` 做日志轮转
- **开机自启**：`pm2 startup` + `pm2 save` 生成 systemd、launchd 等 init 脚本，重启后自动恢复进程列表
- **容器友好**：`pm2-runtime` 作为 `node` 的 drop-in 替代，适合 Docker 镜像中以前台方式运行 Node 应用

## 对用户价值

手写 `nohup node app.js &` 难以应对崩溃重启、滚动发布与多实例调度；裸跑 `node cluster` 又缺少统一的管理界面与日志入口。PM2 把「启动—监控—重启—扩缩—发布」收敛到一套 CLI，让个人 VPS 与小团队也能获得接近 PaaS 的进程治理能力，而无需立刻引入 Kubernetes。对已有 Node 后端，迁移成本通常很低：多数场景只需把启动命令换成 `pm2 start`，再按需配置 ecosystem 文件与开机脚本。

## 与替代方案

- 相比 **nodemon**，PM2 面向生产守护与集群调度，nodemon 侧重开发时文件变更自动重启，二者常搭配使用（开发用 nodemon，上线用 PM2）。
- 相比 **forever**，PM2 功能面更完整（集群模式、零停机 reload、监控面板、startup 脚本、Docker runtime），社区体量与文档也更成熟；forever 更轻量，适合只需简单 keep-alive 的场景。
- 相比 **systemd 直接管理 node 单元**，PM2 提供应用级进程列表、日志与热重载抽象，单机多 Node 服务时运维心智负担更低；若团队已全面容器化并由 K8s 编排，PM2 的价值主要在 VM/裸机或简单 Docker 部署层。
- 相比 **Docker + K8s**，PM2 适合单台或少量服务器的 Node 守护，无需编排集群即可落地；K8s 适合多服务、弹性伸缩与复杂发布流水线，但学习与运维成本更高。
- **边界说明**：PM2 主要解决进程级治理，不替代反向代理（Nginx）、服务发现或配置中心；许可证为 **AGPL-3.0**，若需闭源商用分发或 SaaS 嵌入，应评估合规或联系官方获取其他许可。

## 适应人群

- 在 VPS、裸机或简单 Docker 环境部署 Node.js/Bun 后端，需要崩溃自愈与日志集中查看的全栈工程师。
- 希望用集群模式吃满多核 CPU、并以零停机方式发布 API 服务的后端与 DevOps 工程师。
- 维护多台 Linux/macOS 服务器、需要统一 `pm2 list` 管理进程并配置开机自启的中小团队运维。

## 如何使用

### 前置条件

- 操作系统：Linux、macOS 或 Windows。
- 运行时：Node.js 18+，或 Bun 1+（仅 Bun 时需将 `node` 指向 Bun 的兼容运行时，详见官方 README）。
- 包管理：npm 或 bun 可用于全局安装 PM2 CLI。

### 安装方式

**通过 npm（推荐）：**

```bash
npm install pm2 -g
```

**通过 Bun：**

```bash
bun install pm2 -g
```

仅安装 Bun、无 Node.js 时，需让 PM2 的 shebang 能解析到 Bun：

```bash
sudo ln -s $(which bun) /usr/local/bin/node
```

升级 PM2：

```bash
npm install pm2@latest -g
pm2 update
```

### 首次运行

```bash
# 守护启动应用
pm2 start app.js

# 查看进程列表
pm2 list

# 集群模式（按 CPU 核数）
pm2 start api.js -i max

# 保存当前进程列表（配合开机自启）
pm2 save
```

生成开机自启脚本（按提示执行输出的 sudo 命令）：

```bash
pm2 startup
pm2 save
```

Docker 中以前台方式运行（示例）：

```dockerfile
RUN npm install pm2 -g
CMD [ "pm2-runtime", "npm", "--", "start" ]
```

### 验证是否成功

```bash
pm2 --version          # 应输出版本号
pm2 list               # 应显示 online 状态的应用
pm2 describe app       # 查看单应用详情（将 app 换为实际名称或 id）
pm2 logs               # 应能看到应用标准输出/错误日志
```

确认 `pm2 startup` 后重启机器，`pm2 list` 中进程应自动恢复为 online。

### 常见坑 / 注意事项

- **AGPL-3.0 许可**：修改 PM2 并以网络服务形式提供时可能触发 AGPL 义务；商业闭源场景请先阅读 README License 段或联系 Keymetrics。
- **集群模式仅限 Node 集群场景**：`-i` 多实例主要面向 Node.js HTTP 等可集群化的应用；非 Node 二进制或脚本需单独评估是否适合 cluster。
- **仅 Bun 环境**：除 symlink `node` 外，部分生态工具仍假设真实 Node.js，混用前应实测目标依赖。
- **日志磁盘占满**：生产环境建议 `pm2 install pm2-logrotate` 并配置轮转策略，避免长期 `pm2 logs` 不写回导致磁盘爆满。
- **`pm2 update` 与进程列表**：升级 PM2 后执行 `pm2 update` 以平滑迁移守护进程；重大版本升级前阅读 [CHANGELOG](https://github.com/Unitech/pm2/blob/master/CHANGELOG.md)。
- **PM2+ 云服务**：官方提供 [PM2+ 监控面板](https://app.pm2.io/)（可选），开源 CLI 本身可离线使用，无需绑定 SaaS。

---

# paperless-ngx

> 社区维护的自托管文档管理系统，扫描、OCR 与全文检索，把纸质档案数字化归档。

- 页面：https://www.niceshare.site/github/paperless-ngx/
- 仓库：https://github.com/paperless-ngx/paperless-ngx
- 官网：https://docs.paperless-ngx.com
- 语言：Python
- Stars：42253
- 许可证：GPL-3.0
- 标签：知识管理、自动化、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Paperless-ngx 是原 Paperless 与 Paperless-ng 的官方继任项目，由社区团队共同维护。它把扫描件、PDF 与邮件附件统一入库，通过 OCR 与元数据索引变成可检索的私有文档库，目标是让实体纸张真正「少留一点」。

## 核心特性

- 支持 PDF、图片与常见办公文档，自动提取文本并建立全文索引
- 基于 Tesseract 的 OCR，可选机器学习辅助自动打标签与分类
- 消费目录（Consumption folder）与邮件收件，文件放入即自动处理
- 标签、通信方、文档类型与自定义字段，便于组织发票、合同与证件
- 多用户权限、REST API 与 Angular Web 界面，适合长期自托管部署
- 官方提供 Docker Compose 模板与一键安装脚本，迁移自 Paperless-ng 较简单

## 对用户价值

纸质发票、保单、合同往往散落在抽屉与邮箱里，检索靠记忆、备份靠运气。Paperless-ngx 把「扫描 → 识别 → 归档 → 搜索」串成固定流程，数据留在自有服务器，比把 PDF 丢进云盘再手动命名更可持续。

## 与替代方案

- 相比原 Paperless-ng，Paperless-ngx 由组织化社区接手，文档、CI 与发布节奏更稳定，是现有用户的推荐升级路径。
- 相比 Mayan EDMS 等企业级 DMS，Paperless-ngx 更轻量，聚焦个人与小型团队的扫描归档场景。
- 相比 Google Drive、iCloud 等云存储，自托管方案隐私可控，且针对 OCR 与文档元数据做了专门优化；但需要自行维护服务器与备份。
- 若只需协作编辑 Office 文档，应优先考虑 Notion、飞书等；Paperless-ngx 强项在「已生成 PDF/扫描件」的长期归档。

## 适应人群

- 想数字化家庭账单、证件与医疗记录，又不愿把敏感文件交给公有云的用户。
- 小型工作室或自由职业者，需要统一归档发票、合同与客户往来邮件。
- 已有 Homelab / NAS，希望用 Docker 跑一套私有文档库的 self-host 爱好者。

## 如何使用

### 前置条件

- 推荐环境：Linux 服务器或 NAS，已安装 Docker 与 Docker Compose。
- 准备足够磁盘空间存放原始文件与数据库；扫描仪或稳定的 PDF 来源。
- 了解 GPL-3.0 许可；**敏感文档以明文存储，务必在可信内网主机运行并做好备份**（官方安全说明强调勿部署在不可信主机）。

### 安装方式

官方推荐 Docker Compose。可用一键脚本生成配置：

```bash
bash -c "$(curl -L https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"
```

也可直接使用仓库 [`docker/compose`](https://github.com/paperless-ngx/paperless-ngx/tree/main/docker/compose) 目录中的 Compose 文件，从 GitHub Container Registry 拉取镜像。其他安装方式见[官方文档](https://docs.paperless-ngx.com/setup/#installation)。

### 首次运行

按脚本或文档完成数据库、Redis 与 Paperless 服务配置后启动栈，在 Web 界面创建管理员账户。将测试 PDF 或扫描图片放入 consumption 目录，或通过界面上传，观察是否自动 OCR 并出现在文档列表。

### 验证是否成功

- 浏览器可访问 Web UI 并完成登录。
- 上传的文档在列表中可见，全文搜索能命中 OCR 提取的内容。
- 可为文档添加标签、通信方，确认元数据保存正常。

### 常见坑 / 注意事项

- 默认不对文档内容加密，生产环境请限制网络暴露、启用 HTTPS，并定期备份数据库与 `media` 目录。
- OCR 质量高度依赖扫描分辨率与对比度，模糊或倾斜页面识别率会明显下降。
- 首次大批量导入可能占用较多 CPU 与磁盘 I/O，建议分批处理。
- 从 Paperless-ng 迁移通常只需替换 Docker 镜像，但升级前仍应阅读 [Migrating 文档](https://docs.paperless-ngx.com/setup/#migrating-to-paperless-ngx) 并做好快照。

---

# Marketing Skills

> Corey Haines 出品的 AI 营销技能库，48 个 SKILL.md 覆盖 CRO、文案、SEO、增长与数据分析全场景。

- 页面：https://www.niceshare.site/github/marketingskills/
- 仓库：https://github.com/coreyhaines31/marketingskills
- 官网：https://marketing-skills.com
- 语言：JavaScript
- Stars：41647
- 许可证：MIT
- 标签：AI 编程、Agent、工作流
- 收录：2026-07-25（更新于 2026-07-25）

## 项目介绍

Marketing Skills 是 Corey Haines 维护的一套 **面向 AI 代理的营销技能库**，把转化优化、文案、SEO、数据分析与增长工程等营销工作，封装成一批结构化的 `SKILL.md` 工作流。它遵循 [Agent Skills 规范](https://agentskills.io)，可在 Claude Code、OpenAI Codex、Cursor、Windsurf 等支持该规范的代理中直接使用。所有技能以 `product-marketing`（产品营销上下文）为公共地基——其它技能在动手前都会先读取它，以理解你的产品、受众与定位，再套用对应框架。

## 核心特性

- **48 项营销技能**：覆盖 CRO、文案、SEO、付费投放、数据度量、留存、增长工程、销售/RevOps 与策略九大类，含 `cro`、`copywriting`、`seo-audit`、`analytics`、`ab-testing`、`churn-prevention` 等
- **技能相互引用**：以 `product-marketing` 为共享上下文，`copywriting ↔ cro ↔ ab-testing`、`revops ↔ sales-enablement ↔ cold-email` 等形成依赖网，避免各自为战
- **自动触发 + 显式调用**：代理识别到营销任务时自动套用对应框架，也支持 `/cro`、`/emails`、`/seo-audit` 等斜杠命令直接调用
- **多宿主安装**：官方推荐 `npx skills` 一键安装，另提供 Claude Code 插件、Git 克隆/子模块、SkillKit 多代理等六种接入方式
- **纯 Markdown 交付**：技能即知识文件，无运行时依赖，可随项目版本化、按需裁剪与二次定制

## 对用户价值

通用编码 Agent 在营销任务上往往缺乏方法论：写落地页不懂转化框架、做 SEO 审计漏掉关键项、发冷启邮件套路化。Marketing Skills 把资深营销人的判断编码成可复用工作流——何时该做客户调研、落地页按什么结构改、A/B 实验怎么设计。对独立创始人，它相当于把一位懂增长的营销顾问接进终端；对技术型营销团队，它提供可版本化、跨工具复用的营销执行标准。

## 与替代方案

- 相比 [Agent Skills](https://github.com/addyosmani/agent-skills)、[Superpowers](https://github.com/obra/superpowers) 等 **通用软件工程技能库**，本仓库聚焦营销垂类（CRO、文案、SEO、增长），领域框架而非研发流程是其核心差异。
- 相比 [Anthropic Agent Skills](https://github.com/anthropics/skills) 官方规范与示例，这里是 **面向单一职能（营销）的成体系技能集**，二者可组合——用官方格式分发，用本仓库补齐营销专业知识。
- 相比通用 ChatGPT / Claude 营销提示词合集，Skills 以 `product-marketing` 共享上下文 + 技能互引组织，**按任务渐进加载**，比零散 Prompt 更结构化、可维护。

## 适应人群

- 使用 Claude Code、Cursor 或 Codex，希望代理承接 CRO、文案、SEO 等营销任务的技术型营销人。
- 需要独立完成增长全链路、又缺乏专职营销团队的独立开发者与创始人。
- 想为团队沉淀可版本化、可跨工具复用营销执行标准的增长负责人。

## 如何使用

### 前置条件

- 一个支持 Agent Skills 规范的宿主：Claude Code、Codex、Cursor、Windsurf 等。
- 目标项目具备读写权限；建议先准备好产品/受众/定位信息，供 `product-marketing` 技能建立上下文。
- 已安装 Node.js，以便使用官方推荐的 `npx skills` 安装方式。

### 安装方式

**CLI 安装（官方推荐）**

```bash
# 安装全部技能
npx skills add coreyhaines31/marketingskills

# 仅安装指定技能
npx skills add coreyhaines31/marketingskills --skill cro copywriting

# 列出全部可用技能
npx skills add coreyhaines31/marketingskills --list
```

在 Agent 会话内运行时，需显式指定代理，否则可能只装到通用 `.agents/skills/` 目录：

```bash
npx skills add coreyhaines31/marketingskills -a claude-code
```

**Claude Code 插件**

```
/plugin marketplace add coreyhaines31/marketingskills
/plugin install marketing-skills
```

**克隆复制**

```bash
git clone https://github.com/coreyhaines31/marketingskills.git
cp -r marketingskills/skills/* .agents/skills/
```

多代理批量安装可用 [SkillKit](https://github.com/rohitg00/skillkit)：`npx skillkit install coreyhaines31/marketingskills`。

### 首次运行

安装后新开会话，直接用自然语言描述营销任务，例如「帮我优化这个落地页的转化」或「给我的 SaaS 写首页文案」。代理应自动触发 `cro`、`copywriting` 等对应技能；也可用 `/cro`、`/seo-audit` 直接调用。

### 验证是否成功

发起营销请求后，确认代理引用了具体 skill 名称并按其框架分步执行（而非泛泛作答）；斜杠命令（如 `/emails`）可被识别即安装成功。

### 常见坑 / 注意事项

- 在代理会话内运行 CLI 时若不加 `-a claude-code`，可能只装到 Claude Code 不读取的通用目录，导致技能「装了却不生效」。
- 从 v1.x 升级到 v2.0 有 17 个技能改名、`page-cro`+`form-cro` 合并为 `cro`；旧目录不会自动清理，需按 README 手动删除并迁移 `product-marketing` 上下文文件。
- 技能为纯 Markdown，实际效果取决于宿主实现与模型版本，关键营销决策仍需人工复核。
- MIT 许可，可自由用于个人与商业项目。

---

# Cobalt

> 无广告、无追踪的开源媒体下载器，支持 YouTube/TikTok 等 20+ 平台，可自托管 API 与 Web 前端。

- 页面：https://www.niceshare.site/github/cobalt/
- 仓库：https://github.com/imputnet/cobalt
- 官网：https://cobalt.tools
- 语言：Svelte
- Stars：40948
- 许可证：AGPL-3.0
- 标签：开发工具、网络工具、自动化
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

[Cobalt](https://cobalt.tools) 是一款注重体验的开源媒体下载工具：粘贴公开链接即可获取视频、音频或图片，无广告、无追踪、无付费墙。项目以 monorepo 形式维护 Web 前端、Express API 与相关包；服务端不缓存内容，通过隧道代理与 ffmpeg 转封装完成下载，适合希望自建实例或对接 API 的开发者，也适合只想「贴链接、拿文件」的普通用户。

## 核心特性

- **多平台支持**：覆盖 YouTube（含 Shorts、8K/HDR）、TikTok、Instagram、Twitter/X、Reddit、SoundCloud、Bilibili、Vimeo、VK 等 20+ 服务，可按平台选择仅视频、仅音频或元数据
- **简洁 Web 体验**：官方站点 [cobalt.tools](https://cobalt.tools) 提供零干扰界面；API 支持画质、码率、容器格式、字幕语言等细粒度参数
- **代理式架构**：内容不落盘缓存，以隧道（tunnel）流式转发或本地 remux，降低存储与合规风险
- **可自托管**：推荐 Docker Compose 一键部署（含 Watchtower 自动更新）；也支持 Node.js + pnpm 本地开发运行
- **实例防护**：文档支持 API Key、Cloudflare Turnstile、速率限制等，便于公开实例防滥用
- **AGPL-3.0 开源**：API 与整体仓库均开源，修改分发需遵循 AGPL 义务

## 对用户价值

商业下载站常夹杂广告、弹窗与数据收集；命令行工具（如 yt-dlp）功能强但学习成本高。Cobalt 把「解析 → 选格式 → 下载」收成一步，公开实例开箱即用，自托管则可完全掌控数据路径与访问策略。对创作者与运维者，自建 API 还能嵌入内部工具链；对注重隐私的用户，无追踪、不缓存的设计比第三方在线转换站更透明。项目明确仅面向**可免费公开访问**的内容，不承担终端用户的使用责任。

## 与替代方案

- 相比 **[yt-dlp](https://github.com/yt-dlp/yt-dlp)**，Cobalt 提供现成 Web UI 与 JSON API，部署后即可给非技术用户用；yt-dlp 平台覆盖更广、脚本化更强，适合纯 CLI 与批处理场景。
- 相比 **[youtube-dl](https://github.com/ytdl-org/youtube-dl)**（维护放缓），Cobalt 持续迭代多平台解析，并内置现代前端与实例防护文档。
- 相比 **SaveFrom、Y2Mate 等在线下载站**，Cobalt 开源可审计、无广告追踪，且可自托管避免第三方服务下线或注入脚本。
- 相比 **[gallery-dl](https://github.com/mikf/gallery-dl)**（偏图库/相册批量抓取），Cobalt 聚焦短视频与社交平台链接，Web 交互更轻。
- **官方托管 API**（如 `api.cobalt.tools`）带 Bot 防护，**不建议**未授权接入第三方项目；需稳定集成时应[自建实例](https://github.com/imputnet/cobalt/blob/main/docs/run-an-instance.md)或向实例所有者申请访问。

## 适应人群

- 希望无广告、无账号下载 YouTube/TikTok/Instagram 等公开内容的普通用户（使用官方站或自建前端）。
- 需要为团队或产品提供媒体抓取 API、并愿意用 Docker 自托管的开发者。
- 关注隐私与透明架构、不愿把链接交给不可信在线转换站的内容创作者与运维者。

## 如何使用

### 前置条件

**使用官方 Web 站（最简单）**

- 现代浏览器与可访问 [cobalt.tools](https://cobalt.tools) 的网络环境
- 待下载内容为各平台**公开可访问**的链接

**自托管 API（Docker，推荐）**

- 已安装 [Docker](https://docs.docker.com/engine/install/) 与 [Docker Compose](https://docs.docker.com/compose/install/)
- 若实例面向公网：准备域名、反向代理（如 Nginx），并建议配置 [Turnstile 或 API Key 防护](https://github.com/imputnet/cobalt/blob/main/docs/protect-an-instance.md)

**本地开发运行 API**

- Node.js ≥ 18、Git、[pnpm](https://pnpm.io/)
- Ubuntu 22.04 上若 ffmpeg 静态二进制 DNS 异常，需安装并启动 `nscd`（见[官方说明](https://github.com/imputnet/cobalt/issues/101#issuecomment-1494822258)）

### 安装方式

**Docker Compose（生产推荐）**

```sh
mkdir cobalt && cd cobalt
# 将官方示例写入 docker-compose.yml 并修改 API_URL
# https://github.com/imputnet/cobalt/blob/main/docs/examples/docker-compose.example.yml
docker compose up -d
```

示例中默认镜像为 `ghcr.io/imputnet/cobalt:11`，需将 `API_URL` 改为你的实例公网地址（末尾保留 `/`），否则隧道下载会异常。部分需登录才能看的公开内容，可在同目录放置 `cookies.json` 并在 compose 中挂载（见 [cookies 示例](https://github.com/imputnet/cobalt/blob/main/docs/examples/cookies.example.json)）。

**源码本地运行 API**

```sh
git clone https://github.com/imputnet/cobalt
cd cobalt/api
pnpm install
# 在 api 目录创建 .env，至少设置 API_URL（本地开发可用 http://localhost:9000/）
pnpm start
```

环境变量完整列表见 [api-env-variables.md](https://github.com/imputnet/cobalt/blob/main/docs/api-env-variables.md)。

### 首次运行

1. **Web 用户**：打开 [cobalt.tools](https://cobalt.tools)，粘贴媒体链接，按需选择画质或「仅音频」，点击下载。
2. **自托管用户**：确认容器运行后，将前端或自写客户端指向你的 `API_URL`；公网实例建议先完成 Turnstile / API Key 配置。
3. **API 调用**：向 `POST /` 发送 JSON（`Content-Type` 与 `Accept` 均为 `application/json`），body 至少包含 `url` 字段；若实例启用鉴权，按文档添加 `Authorization` 头。详见 [API 文档](https://github.com/imputnet/cobalt/blob/main/docs/api.md)。

### 验证是否成功

- Web：页面返回下载或跳转，文件可正常播放/打开。
- 自托管 API：访问 `GET /` 应返回 JSON，包含 `cobalt.version`、`cobalt.services` 等实例信息。
- `POST /` 测试公开 YouTube 或 TikTok 链接，响应 `status` 为 `tunnel`、`redirect` 或 `picker` 之一，且 `url` 可下载。
- Docker 部署：`docker compose ps` 显示 `cobalt` 容器为 running；Watchtower 容器正常则镜像会定期自动更新。

### 常见坑 / 注意事项

- **`API_URL` 配置错误**：自托管最常见问题；必须使用外部可访问的完整 URL（含 `https://` 与尾部 `/`），与反向代理域名一致。
- **勿滥用官方托管 API**：文档明确公开实例有 Bot 防护，未授权集成会被拒；产品集成请自建实例。
- **平台可用性波动**：Twitter/X 等站点可能因对方策略变化导致解析不稳定；README 服务表会标注支持程度（✅/❌/➖）。
- **合规与版权**：仅下载你有权获取的公开内容；Cobalt 不提供盗版能力，用户需自行承担使用与分发责任。
- **AGPL-3.0**：修改 API 或整体服务并对外提供时，需按许可证公开源码并保留版权声明。
- **Cookies 需求**：部分平台公开内容仍需 Cookie 才能拉取，按文档配置 `cookies.json` 并限制实例访问范围。

---

# Claude How To

> Claude Code 可视化教程库，从 Slash Commands 到 Agent 编排，附可复制模板与渐进学习路径。

- 页面：https://www.niceshare.site/github/claude-howto/
- 仓库：https://github.com/luongnv89/claude-howto
- 官网：http://luongnv.com/claude-howto/
- 语言：Python
- Stars：39120
- 许可证：MIT
- 标签：AI 编程、Agent、工作流
- 收录：2026-07-03（更新于 2026-07-03）

## 项目介绍

Claude How To 是由 luongnv89 维护的 **Claude Code 可视化教程库**，口号是「Master Claude Code in a Weekend」。仓库把官方文档里分散的特性说明，整理成 10 个渐进模块：从 Slash Commands、Memory、Skills 到 Hooks、MCP、Subagents、Plugins 与 Checkpoints，每个模块配有 Mermaid 图解、生产级可复制模板，以及带时间估算的学习路线图。README 提供英、越、中、乌、日多语言版本，并随 Claude Code 2.1+ 持续更新（当前 v2.1.160）。

## 核心特性

- **10 个教程模块**：覆盖 Slash Commands、Memory、Skills、Subagents、MCP、Hooks、Plugins、Checkpoints、Advanced Features 与 CLI Reference
- **可复制模板**：`.claude/commands/`、`CLAUDE.md`、Hook 脚本、MCP 配置、Subagent 定义与完整 Plugin 包，复制即可用
- **Mermaid 图解**：说明各特性内部工作原理，强调「为什么」而不只是「怎么用」
- **渐进学习路径**：初学者到高级用户约 11–13 小时，15 分钟即可跑通第一个 Slash Command
- **内置自测**：在 Claude Code 内运行 `/self-assessment` 或 `/lesson-quiz [topic]`，定位知识盲区并生成个性化路线
- **多语言与离线阅读**：含中文 README；可用 `uv run scripts/build_epub.py` 导出 EPUB 电子书

## 对用户价值

很多人装完 Claude Code 只会聊天，不知道如何把 Commands、Hooks、Skills 与 Subagents 串成真正省时的流水线。本仓库解决三个痛点：官方文档偏功能参考、缺少组合示例；学习顺序不清晰；示例过于基础。你可以 15 分钟内复制 `optimize` 命令体验价值，再按路线图逐步搭建代码审查、CI/CD 自动化、文档生成等复合工作流。对团队而言，它是可 Fork 的 onboarding 教材；对个人而言，比零散搜教程更省时间。

## 与替代方案

- 相比 [Anthropic 官方文档](https://code.claude.com/docs)，本库是 **教程 + 模板 + 学习路径**，官方文档更适合查 API 细节；二者互补，建议先学本库再查官方。
- 相比 [Claude Code Best Practice](https://github.com/shanraisshan/claude-code-best-practice) 等 **社区技巧聚合库**，本库侧重 **模块化渐进教学与可视化图解**，并内置 `/self-assessment` 自测；若你需要工作流横评与 80+ 条 Tips 索引，可配合 Best Practice 使用。
- 相比 [Superpowers](https://github.com/obra/superpowers) 等 **可安装技能方法论**，这里是 **教程仓库而非 npm 插件**；若目标是开箱即用的 TDD / 子代理技能链，应直接安装 Superpowers，再用本库理解各原语如何组合。
- 本仓库 **不提供模型路由或 CLI 代理**；跨模型需求需配合 MCP 或第三方 Router 工具。

## 适应人群

- 已安装 Claude Code，想从「会聊天」进阶到编排 Agents、Hooks、Skills 的开发者。
- 需要为团队建立 Claude Code 培训材料、可复制 `.claude/` 配置模板的 Tech Lead。
- 偏好可视化教程与渐进路径，希望 15 分钟见效再系统深入的学习型用户。

## 如何使用

### 前置条件

- 已安装 [Claude Code CLI](https://code.claude.com/docs/en/quickstart)（v2.1+；`npm install -g @anthropic-ai/claude-code` 或原生二进制均可）并完成 Anthropic 账号认证。
- 本机有 Git；克隆仓库需访问 GitHub。企业网络需放行 `https://downloads.claude.ai/claude-code-releases`（v2.1.116+ 下载源）。
- 理解本库定位为 **教程 + 模板**，不是独立 npm 包；核心收益来自阅读模块与复制配置到目标项目。

### 安装方式

克隆仓库到本地：

```bash
git clone https://github.com/luongnv89/claude-howto.git
cd claude-howto
```

将第一个 Slash Command 复制到你的项目（把 `/path/to/your-project` 换成实际路径）：

```bash
mkdir -p /path/to/your-project/.claude/commands
cp 01-slash-commands/optimize.md /path/to/your-project/.claude/commands/
```

可选：一次性完成 1 小时基础配置：

```bash
cp 01-slash-commands/*.md .claude/commands/
cp 02-memory/project-CLAUDE.md ./CLAUDE.md
cp -r 03-skills/code-review-specialist ~/.claude/skills/
```

在目标项目目录启动 Claude Code：

```bash
claude
```

### 首次运行

在 Claude Code 会话中输入：

```bash
/optimize
```

或运行自测命令定位学习起点：

```bash
/self-assessment
```

按 [LEARNING-ROADMAP.md](https://github.com/luongnv89/claude-howto/blob/main/LEARNING-ROADMAP.md) 从对应等级模块开始；初学者建议从 [01-slash-commands](https://github.com/luongnv89/claude-howto/tree/main/01-slash-commands) 入手。

### 验证是否成功

- `/optimize` 等 Slash Command 能正常触发并执行预期流程。
- 项目根目录存在从 `02-memory/project-CLAUDE.md` 复制的 `CLAUDE.md`，且 Claude Code 能读取项目记忆。
- 若已复制 Skill，`code-review-specialist` 等能力可在相关任务中被自动调用。
- 完成模块后可运行 `/lesson-quiz hooks`（或其他 topic）检验理解程度。

### 常见坑 / 注意事项

- 复制模板时务必区分 **项目级**（`.claude/`、`CLAUDE.md`）与 **用户级**（`~/.claude/skills/`、`~/.claude/hooks/`）路径，混用会导致命令找不到或权限问题。
- Hook 脚本复制后需 `chmod +x ~/.claude/hooks/*.sh`；MCP 配置常需额外环境变量（如 `GITHUB_TOKEN`）。
- 企业代理可能阻断 Claude Code 原生二进制下载，需提前放行 `downloads.claude.ai`。
- 仓库随 Claude Code 版本快速迭代，实施前对照 [CHANGELOG](https://github.com/luongnv89/claude-howto/blob/main/CHANGELOG.md) 与官方 Changelog 核实命令是否仍可用。
- 全路径约 11–13 小时，不必一次学完；15 分钟复制一个命令即可获得即时价值。

---

# Fastify

> 面向 Node.js 的高性能低开销 Web 框架，以 JSON Schema 路由校验与插件生态著称。

- 页面：https://www.niceshare.site/github/fastify/
- 仓库：https://github.com/fastify/fastify
- 官网：https://www.fastify.dev
- 语言：JavaScript
- Stars：36558
- 许可证：MIT
- 标签：开发工具、后端、CLI
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Fastify 是面向 Node.js 的 Web 框架，设计灵感来自 Hapi 与 Express，但把**低开销与开发体验**放在同等优先级。它通过 hooks、plugins 与 decorators 提供可扩展架构，推荐用 JSON Schema 校验请求与序列化响应，并在内部将 schema 编译为高性能函数。日志默认集成 [Pino](https://github.com/pinojs/pino)，在保持可观测性的同时尽量压低 I/O 成本。当前 `main` 分支对应 **Fastify v5**；仍在 v4 的项目可跟踪 [`4.x` 分支](https://github.com/fastify/fastify/tree/4.x)。

## 核心特性

- **高性能**：官方 benchmark 显示在典型路由场景下可达约 7.6 万 req/s 量级（视代码复杂度而定），是 Node.js 生态中速度领先的框架之一
- **Schema 驱动**：可选但推荐的 JSON Schema 路由校验与响应序列化，编译后运行时开销极低，接口契约更清晰
- **插件架构**：hooks、plugins、decorators 三层扩展模型，生态提供 CORS、JWT、Swagger、数据库适配等大量官方与社区插件
- **内置结构化日志**：默认 Pino 集成，JSON 日志便于 ELK/Loki 等管道采集，生产环境可关闭 pretty 输出
- **脚手架与 CLI**：`npm init fastify` 一键生成项目，底层由 [create-fastify](https://github.com/fastify/create-fastify) 与 [fastify-cli](https://github.com/fastify/fastify-cli) 驱动

## 对用户价值

若你正在用 Node.js 构建 API 或 BFF，Fastify 能在 Express 熟悉的「路由 + 中间件」心智模型上，提供更高吞吐与更严格的输入输出校验。Schema 先行让前后端与 OpenAPI 文档对齐更容易，减少「字段漏传/类型漂移」类 bug。插件生态覆盖认证、限流、ORM 等常见需求，团队不必从零拼装中间件栈。对已有 Express 项目，迁移路径相对清晰（路由与 handler 语义相近），性能敏感路径可逐步替换。

## 与替代方案

- 相比 **Express**，Fastify 默认性能更高、内置 schema 校验与结构化日志；Express 生态最大、教程与 Stack Overflow 覆盖最广，适合极轻量原型或团队零学习成本场景。
- 相比 **Koa**，Fastify 开箱即用的插件与 schema 体系更完整，benchmark 通常更快；Koa 中间件洋葱模型更极简，适合喜欢自行组装、追求最小核心的团队。
- 相比 **Hono**，Hono 强调边缘运行时（Cloudflare Workers、Deno 等）与 Web 标准 API 统一；Fastify 深耕 Node.js 服务端，插件成熟度、企业级中间件与长期 LTS 分支（4.x）更适合传统 VPS/K8s 部署。
- 边界说明：Fastify 是 HTTP 框架而非 ORM、消息队列或全栈 meta-framework；CPU 密集任务仍需 Worker Threads 或外部服务；`.listen()` 默认绑定 localhost，容器部署需显式 `0.0.0.0` 并评估安全风险。

## 适应人群

- 用 Node.js 构建 REST/GraphQL API、微服务或 BFF 的后端与全栈工程师。
- 从 Express/Koa 迁移、希望在同等代码复杂度下提升吞吐与可观测性的技术负责人。
- 需要 JSON Schema 驱动接口契约、并计划对接 OpenAPI/Swagger 文档的 API 设计团队。

## 如何使用

### 前置条件

- Node.js 运行环境（v5 详见[官方兼容性说明](https://fastify.dev/docs/latest/Guides/Getting-Started/)）。
- 包管理器：npm、yarn 或 pnpm 均可；下文以 npm 为例。

### 安装方式

**方式一：脚手架新建项目（推荐首次体验）**

```bash
mkdir my-app && cd my-app
npm init fastify
npm i
```

**方式二：在现有项目中安装依赖**

```bash
npm i fastify
```

### 首次运行

脚手架项目开发模式：

```bash
npm run dev
```

生产模式：

```bash
npm start
```

最小可运行示例（CommonJS）：

```js
const fastify = require('fastify')({ logger: true })

fastify.get('/', async (request, reply) => {
  return { hello: 'world' }
})

fastify.listen({ port: 3000 }, (err, address) => {
  if (err) throw err
})
```

ESM 项目将 `require` 换为 `import Fastify from 'fastify'` 即可。更多示例见[官方 Getting Started](https://fastify.dev/docs/latest/Guides/Getting-Started/)与 [demo 仓库](https://github.com/fastify/demo)。

### 验证是否成功

- 开发或生产命令启动后无报错退出。
- 访问 `http://127.0.0.1:3000/` 应返回 `{"hello":"world"}`（或你定义的路由响应）。
- 若启用 `logger: true`，控制台应出现 Pino 结构化请求日志。

### 常见坑 / 注意事项

- **监听地址**：`.listen()` 默认绑定 `localhost`（`127.0.0.1` / `::1`）；Docker、GCP 等容器内需显式 `{ host: '0.0.0.0', port: 3000 }`，并注意暴露端口的网络安全。
- **大版本分支**：`main` 为 v5；生产若仍依赖 v4 API，请锁定 4.x 版本并阅读 [迁移指南](https://fastify.dev/docs/latest/Guides/Migration-Guide-V5/)。
- **Schema 可选但推荐**：跳过 schema 仍可运行，但会失去编译期校验与自动序列化的性能与契约收益。
- **插件注册顺序**：部分插件（如 `@fastify/cors`、认证插件）对注册顺序敏感，升级插件大版本前请查阅对应 README 与 CHANGELOG。

---

# Marker

> 高精度将 PDF 及 Office 文档转为 Markdown/JSON，支持表格、公式、图片提取与多语言 OCR。

- 页面：https://www.niceshare.site/github/marker/
- 仓库：https://github.com/datalab-to/marker
- 官网：https://www.datalab.to
- 语言：Python
- Stars：36230
- 许可证：GPL-3.0
- 标签：知识管理、开发工具、自动化
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

[Marker](https://github.com/datalab-to/marker) 是 Datalab 开源的文档智能工具，可将 PDF、图片及常见 Office 格式快速转换为 Markdown、JSON、HTML 或分块文本。项目在表格、公式、表单与多栏版式等复杂场景上表现突出，支持 GPU/CPU/MPS 本地推理，也可通过 `--use_llm` 接入 Gemini 或 Ollama 进一步提升准确率，适合构建 RAG 语料、知识库导入或文档自动化流水线。

## 核心特性

- **多格式输入**：支持 PDF、图片、PPTX、DOCX、XLSX、HTML、EPUB，覆盖多语言文档
- **结构化输出**：可导出 Markdown、JSON、HTML 或 chunks，保留表格、链接、参考文献与代码块
- **版式与公式处理**：格式化表格与表单，支持行内/块级公式转 LaTeX，可提取并保存嵌入图片
- **智能清理**：自动去除页眉页脚等版面噪声，可选强制 OCR 或剥离已有 OCR 文本
- **可扩展架构**：处理器与转换器可自定义；支持按 JSON Schema 做结构化抽取（beta）
- **混合模式**：`--use_llm` 可合并跨页表格、修正表单字段、优化行内数学公式
- **批处理与多 GPU**：`marker` 支持文件夹批量转换；`marker_chunk_convert` 可跨多卡并行，H100 上理论吞吐约 25 页/秒

## 对用户价值

扫描件、学术论文、合同与幻灯片往往难以直接喂给 LLM 或检索系统。Marker 把「版面理解 → 结构化文本」收成一条本地可复现的流水线，比手工复制或简单 `pdftotext` 更能保留表格与公式语义。对需要私有化部署的团队，可在自有 GPU 上批量跑转换，避免把敏感文档上传第三方 SaaS；对研究者与工程师，输出的 Markdown/JSON 可直接接入向量库、笔记工具或下游 ETL。官方还提供 [Playground](https://www.datalab.to/playground) 与托管 API，便于先验证效果再决定是否自托管。

## 与替代方案

- 相比 **[LlamaParse](https://www.llamaindex.ai/llamaparse)**、**Mathpix** 等云服务，Marker 可完全本地运行，数据不出内网；云方案运维更轻、但按量计费且依赖外网。
- 相比 **[PyMuPDF](https://pymupdf.readthedocs.io/)**、**pdfplumber** 等纯文本抽取库，Marker 针对复杂版式、表格与公式做了端到端模型推理，准确率更高，但资源占用也更大（单 worker 峰值约 5GB VRAM）。
- 相比 **[Unstructured](https://github.com/Unstructured-IO/unstructured)** 等通用文档解析框架，Marker 更聚焦「高质量 Markdown/JSON 输出」与 PDF 场景，并内置 OCR（Surya）与可选 LLM 后处理。
- 同团队的 **[Chandra](https://github.com/datalab-to/chandra)** 准确率更高，适合对质量极度敏感的场景；Marker 仍是当前 GitHub 上最成熟、社区最广的开源入口。
- **许可注意**：代码为 GPL-3.0，模型权重采用修改版 OpenRAIL-M（研究/个人/年收入或融资低于 200 万美元的创业团队可免费使用）；更广的商业自托管需向 Datalab 购买许可。

## 适应人群

- 需要把 PDF 论文、报告、手册批量转为 Markdown/JSON 以构建 RAG 或知识库的数据工程师与 AI 应用开发者。
- 希望在本地 GPU 上私有化处理合同、扫描件等敏感文档、且对表格/公式还原有要求的法务、金融或研究机构。
- 正在评估文档解析方案、希望用开源工具对标 LlamaParse/Mathpix 并保留自托管能力的工程团队。

## 如何使用

### 前置条件

- Python 3.10 及以上
- 已安装 [PyTorch](https://pytorch.org/get-started/locally/)（支持 CUDA、MPS 或 CPU）
- 若需处理 PDF 以外的格式（PPTX、DOCX 等），需安装 `[full]` 额外依赖
- 使用 `--use_llm` 时需配置 Gemini API Key 或可访问的 Ollama 服务

### 安装方式

```shell
pip install marker-pdf
```

处理 PDF 以外格式时：

```shell
pip install marker-pdf[full]
```

可选：安装 Streamlit 以使用图形界面

```shell
pip install streamlit streamlit-ace
```

### 首次运行

转换单个 PDF 或图片：

```shell
marker_single /path/to/file.pdf
```

指定输出格式与目录：

```shell
marker_single /path/to/file.pdf --output_format markdown --output_dir ./output
```

批量转换文件夹：

```shell
marker /path/to/input/folder --workers 4
```

启动交互式 GUI：

```shell
marker_gui
```

启用 LLM 混合模式（默认 Gemini 2.0 Flash，需配置 API）：

```shell
marker_single /path/to/file.pdf --use_llm
```

多 GPU 并行（示例：4 卡、每卡 15 worker）：

```shell
NUM_DEVICES=4 NUM_WORKERS=15 marker_chunk_convert ../pdf_in ../md_out
```

### 验证是否成功

- 命令结束后，`--output_dir` 下应生成 `.md`、`.json` 或 `.html` 文件及提取的图片目录
- 打开 Markdown 输出，检查表格、标题层级、公式（`$...$` 或 `$$...$$`）是否与原文一致
- 对扫描件可尝试 `--force_ocr` 或 `--strip_existing_ocr`，对比 OCR 质量
- 运行 `marker_single --help` 可列出全部处理器与配置项；`config --help` 可查看可定制的 builder/processor 列表

### 常见坑 / 注意事项

- **显存占用**：每个 worker 峰值约 5GB VRAM，批量时勿盲目拉高 `--workers`，否则易 OOM
- **数字 PDF 乱码**：部分 PDF 内嵌字体异常，需加 `--force_ocr` 强制 OCR；若需保留原有数字文本并去掉劣质 OCR，用 `--strip_existing_ocr`
- **行内公式**：对 inline math 敏感的场景，建议 `--force_ocr` 或配合 `--use_llm --redo_inline_math`
- **商业使用**：代码 GPL-3.0，模型 OpenRAIL-M 对大型商业主体有限制；广泛商用或去 GPL 义务需联系 [Datalab 定价页](https://www.datalab.to/pricing)
- **LLM 模式成本**：`--use_llm` 会调用外部模型 API，大批量文档前请估算 token 费用
- **首次运行下载模型**：需联网拉取权重，内网环境需提前缓存 artifact 或参考文档离线配置

---

# Lerna

> JavaScript/TypeScript monorepo 构建与发布系统，支持跨包任务编排、版本管理与计算缓存。

- 页面：https://www.niceshare.site/github/lerna/
- 仓库：https://github.com/lerna/lerna
- 官网：https://lerna.js.org
- 语言：TypeScript
- Stars：36064
- 许可证：MIT
- 标签：开发工具、自动化、CLI
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Lerna 是面向 JavaScript/TypeScript **monorepo** 的构建与发布系统，自 2016 年起被广泛用于在同一仓库中管理多个 npm 包。2022 年起项目由 [Nx 团队接管维护](https://github.com/lerna/lerna/issues/3121)，核心能力在保留 `lerna version` / `lerna publish` 等经典工作流的同时，接入了 Nx 的任务调度、计算缓存与分布式执行引擎。Lerna **不负责**依赖安装与链接——官方推荐配合 npm、Yarn 或 pnpm 的 **workspaces** 使用，自身专注跨包脚本执行、版本递增与 npm 发布编排。

## 核心特性

- **一键初始化**：`lerna init` 可从零创建带 git 与 workspaces 的 monorepo，也可在现有仓库中接入并识别包路径
- **跨包任务执行**：`lerna run <script>` 按依赖图顺序在全部或部分包上运行 npm scripts，支持 `--scope`、`--since` 增量执行
- **版本与发布**：内置 fixed / independent 两种版本策略，可自动生成 CHANGELOG 并将包发布到 npm
- **计算缓存**：任务结果可本地缓存，避免重复构建；支持与 Nx Cloud 等方案共享远程缓存
- **项目依赖图**：可视化包间依赖关系，帮助理解任务调度顺序与架构边界
- **分布式 CI 执行**：在核心包变更导致全量构建时，可并行分发任务到多个 agent 缩短最坏情况下的 CI 时间

## 对用户价值

若你在一个仓库里维护多个相互依赖的 npm 包（组件库、工具包、示例应用等），Lerna 把「改一个包、测相关包、统一 bump 版本、按序发布」串成可脚本化的流程，减少手工协调。`--since=origin/main` 让 PR 只跑受影响的包，配合缓存可显著缩短 CI 时间。对已有 Lerna 4 及以下版本的老项目，升级到 Nx 时代的 Lerna 5+ 可在保留熟悉 CLI 的前提下获得现代任务引擎，迁移路径比整体换栈更平滑。

## 与替代方案

- 相比 **Nx**，Lerna 与 Nx 共享底层任务调度与缓存能力（Lerna 6+ 由 Nx 驱动）；Nx 提供更完整的生成器、插件生态与 IDE 集成（Nx Console），适合从零规划大型 monorepo；Lerna CLI 更轻、语义贴近「多包版本发布」经典场景，学习曲线对老用户更友好。
- 相比 **Turborepo**，两者都强调任务缓存与 `--filter` / `--since` 式增量构建；Turborepo 以 `turbo.json` pipeline 为中心、与包管理器解耦；Lerna 在 **npm 包版本管理与 publish** 上历史积淀更深，适合需要 fixed/independent versioning 工作流的团队。
- 相比 **pnpm / npm workspaces  alone**，workspaces 只解决包装依赖与链接，不提供跨包任务编排、版本递增与发布；Lerna 补的是「编排层」，两者通常组合使用而非互斥。
- 边界说明：Lerna 不是包管理器或 JavaScript 运行时；依赖安装、hoisting 策略仍由 npm/Yarn/pnpm 决定，接入前需先正确配置 workspaces。

## 适应人群

- 在同一仓库维护多个 npm 包、需要统一版本发布与 CHANGELOG 的前端库与平台工程团队。
- 希望用 `--since` 与任务缓存缩短 monorepo CI 时间、又不愿整体迁移到 Nx 全栈方案的技术负责人。
- 从 Lerna 4 或纯 workspaces 方案升级、需要现代任务调度与分布式缓存的存量 monorepo 维护者。

## 如何使用

### 前置条件

- Node.js 环境（版本要求见 [lerna.js.org 文档](https://lerna.js.org) 与 npm 包说明）。
- 包管理器已启用 **workspaces**（npm / Yarn / pnpm 均可）；Lerna 不负责 `node_modules` 安装与链接。
- 若需发布到 npm，需已登录 `npm login` 并拥有对应包的发版权限。

### 安装方式

**方式一：从零创建 monorepo**

```bash
mkdir ./new-lerna-workspace && cd ./new-lerna-workspace
npx lerna init --dryRun   # 预览变更
npx lerna init            # 确认后正式初始化
```

**方式二：在现有仓库中接入**

```bash
# 已配置 package manager workspaces 时，直接 init 即可识别包路径
npx lerna init

# 或手动指定包目录
npx lerna init --packages="packages/*"
npx lerna init --packages="foo/*" --packages="bar/*"
```

**方式三：作为 devDependency 安装**

```bash
npm install --save-dev lerna
# 或 pnpm add -D lerna / yarn add -D lerna
```

### 首次运行

```bash
# 验证 CLI
npx lerna --version

# 在所有包上执行 build 脚本（按依赖图排序）
npx lerna run build

# 仅对 header 包跑 test
npx lerna run test --scope=header

# 只对相对 main 有改动的包执行任务
npx lerna run test --since=origin/main

# 递增版本（交互式）
npx lerna version

# 发布到 npm
npx lerna publish
```

### 验证是否成功

```bash
npx lerna --version                          # 应输出版本号
npx lerna run build                          # 各包 build 应按序成功，终端显示 ✔ 汇总
npx lerna list                               # 应列出 workspaces 中的包
```

确认根目录已生成 `lerna.json`，且 `package.json` 中 workspaces 配置与 `lerna.json` 的 packages 路径一致。

### 常见坑 / 注意事项

- **依赖安装不归 Lerna 管**：`lerna bootstrap` 在 modern Lerna 中已非推荐路径；请用 `npm install` / `pnpm install` / `yarn install` 配合 workspaces，再执行 `lerna run`。
- **workspaces 与 packages 路径不一致**：`lerna init` 默认读取包管理器的 workspaces 配置；若包未被识别，检查 `lerna.json` 与 `package.json`（或 `pnpm-workspace.yaml`）中的 glob 是否匹配。
- **Nx 时代的行为变化**：Lerna 5+ 任务引擎由 Nx 驱动，缓存、`.env` 自动加载等行为与旧版不同；升级前阅读 [官方迁移指南](https://lerna.js.org) 与 CHANGELOG。
- **发布权限与版本策略**：`lerna version` 的 fixed / independent 模式影响 CHANGELOG 与 tag 语义；首次 publish 前在测试 registry 或 `--dry-run` 下验证。
- **与 Nx 的关系**：项目现由 Nx 团队维护，深度定制任务图、远程缓存或 IDE 集成时可评估是否直接使用 Nx；Lerna 适合保留现有 CLI 习惯的场景。

---

# pnpm

> 高速省磁盘的 Node.js 包管理器，以 content-addressable store 与严格依赖隔离著称。

- 页面：https://www.niceshare.site/github/pnpm/
- 仓库：https://github.com/pnpm/pnpm
- 官网：https://pnpm.io
- 语言：Rust
- Stars：35551
- 许可证：MIT
- 标签：开发工具、CLI、自动化
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

pnpm 是面向 Node.js 生态的包管理器，自 2016 年起在生产环境广泛使用。它通过 **content-addressable store** 将同一版本的包文件集中存储，再在项目 `node_modules` 中以硬链接/符号链接复用，显著节省磁盘并加快安装。pnpm 同时提供 `pnpm-lock.yaml` 锁定依赖、内置 [workspaces](https://pnpm.io/workspaces) 支持 monorepo，并以严格模式限制包只能访问 `package.json` 中声明的依赖，减少「幽灵依赖」带来的隐患。v11 起核心 CLI 以纯 ESM 分发，并可通过 `pnpm runtime` 管理 Node.js 版本。

## 核心特性

- **安装更快**：官方 benchmark 显示常见场景下可比 npm/Yarn 快约 2 倍，全局 store 命中后重复安装几乎瞬时完成
- **磁盘高效**：多项目共享同一 store，同一包版本只存一份实体文件，大型 monorepo 可节省数 GB 空间
- **严格依赖隔离**：非扁平 `node_modules` 结构，子依赖无法被上层「偷偷引用」，更早暴露错误 import
- **Monorepo 一等公民**：`pnpm-workspace.yaml` + filter 命令支持跨包脚本、依赖与发布编排
- **可复现 lockfile**：`pnpm-lock.yaml` 锁定完整依赖图，CI 与本地 `pnpm install --frozen-lockfile` 结果一致
- **Node 版本管理**：`pnpm env` / runtime 可在无 nvm 的情况下安装与切换 Node.js

## 对用户价值

若你维护多个前端/全栈项目，pnpm 的全局 store 能避免每个仓库重复下载相同依赖，本地与 CI 缓存策略也更清晰。对 monorepo 团队，workspaces 与 `pnpm -r` 过滤命令让跨包构建、测试与版本发布保持在 npm 兼容语义下，又比传统扁平 `node_modules` 更可控。严格模式会在开发阶段暴露「用了但没声明」的依赖，减少上线后因环境差异触发的隐蔽 bug。迁移成本通常较低：命令与 npm 高度相似（`pnpm install`、`pnpm add`、`pnpm run`），多数现有 `package.json` 可直接沿用。

## 与替代方案

- 相比 **npm**，pnpm 安装速度与磁盘占用通常更优，依赖隔离更严格；npm 是 Node.js 默认自带、生态文档与第三方教程覆盖最广的选择，团队零学习成本时 npm 仍常见。
- 相比 **Yarn Classic / Berry**，pnpm 的 store + 链接模型在磁盘复用上更激进，workspaces 与 lockfile 工作流成熟；Yarn Berry 的 Plug'n'Play 与 Zero-Install 等特性适合特定团队，但 PnP 与部分工具链兼容性需额外评估。
- 相比 **Bun 内置包管理器**，Bun 把 install/run/test 收进单一运行时，追求极致速度；pnpm 专注包管理与 monorepo，与 Node.js 生态、Corepack 及现有 CI 模板兼容面更广，不绑定特定运行时。
- 边界说明：pnpm 不是 JavaScript 运行时或打包器；部分依赖「扁平 node_modules 副作用」的老旧包、或假设 Yarn/npm hoisting 行为的工具，迁移后可能需要 `shamefully-hoist` 等配置或补丁，宜在目标项目实测。

## 适应人群

- 同时维护多个 Node.js 项目、希望统一依赖缓存并节省磁盘的前端与全栈开发者。
- 使用 Rush、Nx、Turborepo 等编排工具的 monorepo 团队，需要可靠 workspaces 与 lockfile 的工程组织。
- 从 npm/Yarn 迁移、希望在 CI 中加速 install 并减少 phantom dependencies 的技术负责人。

## 如何使用

### 前置条件

- 支持 Windows、Linux、macOS（Apple Silicon 与 arm64/x64）。
- 通过 npm/Corepack 安装时需本机已有 Node.js（pnpm 11 建议 Node.js 22+，详见[兼容性表](https://pnpm.io/installation#compatibility)）。
- 独立安装脚本可在无 Node.js 环境下安装 pnpm；Intel macOS（darwin-x64）不支持 standalone 脚本，请改用 npm、Corepack 或 Homebrew。

### 安装方式

**方式一：独立安装脚本（POSIX，推荐 Apple Silicon / Linux）**

```bash
curl -fsSL https://get.pnpm.io/install.sh | sh -
```

**Windows（PowerShell）**

```powershell
Invoke-WebRequest https://get.pnpm.io/install.ps1 -UseBasicParsing | Invoke-Expression
```

> Windows 上 Defender 可能拦截 standalone 可执行文件，官方更推荐 npm 或 Corepack 安装。

**方式二：Corepack（Node.js 16.13+）**

```bash
npm install --global corepack@latest
corepack enable pnpm
```

在项目中锁定版本：

```bash
corepack use pnpm@latest-11
```

**方式三：npm 全局安装**

```bash
npm install -g pnpm@latest-11
```

**其他方式**

```bash
brew install pnpm          # macOS Homebrew
winget install -e --id pnpm.pnpm   # Windows winget
```

升级：`pnpm self-update`

### 首次运行

```bash
# 验证 CLI
pnpm --version

# 在现有项目中安装依赖
pnpm install

# 添加依赖
pnpm add lodash

# 运行 package.json 脚本
pnpm run dev

# monorepo 根目录执行所有包的 build
pnpm -r run build
```

### 验证是否成功

```bash
pnpm --version                    # 应输出版本号
pnpm install                      # 应生成/更新 node_modules 与 pnpm-lock.yaml
pnpm list --depth 0               # 应列出顶层依赖
```

确认安装脚本提示的 pnpm 路径（如 `~/.local/share/pnpm`）已加入 `PATH`，新开终端后 `which pnpm` 可找到可执行文件。

### 常见坑 / 注意事项

- **严格依赖导致 import 失败**：某些包隐式依赖未声明的 peer/transitive，需在 `package.json` 显式添加，或评估 `.npmrc` 中的 `public-hoist-pattern` / `shamefully-hoist`（迁移期慎用）。
- **Intel Mac 与 standalone**：darwin-x64 不支持独立脚本，请用 npm、Corepack 或 Homebrew；详见 [#11423](https://github.com/pnpm/pnpm/issues/11423)。
- **Linux 最小镜像缺 libatomic**：Alpine 等 musl 环境或精简 glibc 镜像若报 `libatomic.so.1` 缺失，需安装对应系统包（如 Debian/Ubuntu：`apt-get install -y libatomic1`）。
- **Windows Defender 拖慢安装**：可将 `pnpm store path` 输出目录加入 Defender 排除列表以改善 I/O 性能。
- **v11 纯 ESM**：若全局安装路径或旧脚本仍假设 CJS 入口，升级后遇到 `MODULE_NOT_FOUND` 可参照[官方排错文档](https://pnpm.io/installation#troubleshooting)清理旧 CLI 后重装。

---

# Continue

> 开源 AI 编程助手，可作为 IDE 插件、CLI 与团队自定义编码代理使用。

- 页面：https://www.niceshare.site/github/continue/
- 仓库：https://github.com/continuedev/continue
- 官网：https://continue.dev
- 语言：TypeScript
- Stars：34117
- 许可证：Apache-2.0
- 标签：AI 编程、开发工具、Agent
- 收录：2026-06-19（更新于 2026-06-19）

## 项目介绍

Continue 是面向开发者的开源 AI 编程助手，可作为 VS Code、JetBrains 等环境中的日常插件，也可通过 CLI 承载团队自己的模型、提示词和上下文策略。官方仓库目前已只读维护，但 2.0 版本扩展与文档仍可作为学习与自托管参考。

## 核心特性

- 支持 VS Code、JetBrains 等主流 IDE 插件形态
- 可配置多种模型提供方与上下文来源
- 提供 CLI 与团队级编码代理配置能力
- 开源可审计，便于自定义规则与工作流
- 文档覆盖安装、配置与模型接入全流程

## 对用户价值

Continue 的价值在于可组合：开发者可以选择模型、配置上下文来源，并把重复性的编码、解释和重构任务放进熟悉的 IDE 流程里。对于关注隐私和可控性的团队，它比完全黑盒的托管工具更容易评估和治理。

## 与替代方案

- 相比 GitHub Copilot 等托管助手，Continue 更强调开源、可自托管模型与团队自定义规则。
- 相比纯终端 AI 工具（Aider），Continue 更贴近 IDE 内的日常编码节奏。
- 若需要强自主代理与 Kanban 编排，可评估 Cline 等方案。

## 适应人群

- 希望在 IDE 内使用 AI 编程助手的个人开发者。
- 需要统一团队编码代理配置的工程团队。
- 想把本地模型或私有模型接入开发流程的 AI 工具探索者。

## 如何使用

### 前置条件

- 已安装 VS Code 或 JetBrains 等受支持的 IDE。
- 准备好所用模型的 API 密钥或本地模型端点。

### 安装方式

从 [continue.dev](https://continue.dev) 或编辑器扩展市场安装 Continue 插件。

### 首次运行

打开 IDE 中的 Continue 面板，选择模型提供方并完成密钥配置，再指定项目规则与上下文来源。

### 验证是否成功

在项目中发起一次简单问答或代码补全，确认模型响应正常且上下文文件可被读取。

### 常见坑 / 注意事项

- 官方仓库已只读，新功能与长期支持需关注文档与社区 fork 动态。
- 团队推广前先用小仓库验证模型成本、权限边界与上下文范围。
- 私有代码库应明确哪些目录可纳入上下文，避免泄露敏感信息。

---

# fish

> 开箱即用的交互式命令行 Shell，自带语法高亮、自动建议与智能补全，零配置即可上手。

- 页面：https://www.niceshare.site/github/fish-shell/
- 仓库：https://github.com/fish-shell/fish-shell
- 官网：https://fishshell.com
- 语言：Rust
- Stars：33712
- 许可证：GPL-2.0
- 标签：开发工具、CLI、自动化
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

fish（friendly interactive shell）是一款面向 macOS、Linux 及类 Unix 平台的交互式命令行 Shell，以「开箱即用」著称。它在 Rust 核心之上提供语法高亮、输入时自动建议、无需配置的 Tab 补全，以及 Web 配置工具 `fish_config`，让日常终端操作比传统 bash/zsh 更直观，同时仍可与现有脚本和 POSIX 工具链共存。

## 核心特性

- **语法高亮与自动建议**：命令与参数在输入时即着色，历史与路径会灰显建议，按右方向键即可采纳
- **智能 Tab 补全**：基于命令与 man 页生成补全，多数场景无需手写 `complete` 规则
- **Web 配置界面**：运行 `fish_config` 可在浏览器中预览主题、调整提示符与快捷键
- **友好脚本语法**：变量、函数与条件分支语法更贴近现代语言，内置 `help` 与在线文档降低学习成本
- **跨平台安装渠道**：Homebrew、各发行版包管理器、官方安装包与 WSL/Cygwin 均有支持

## 对用户价值

bash 与 zsh 的补全、提示符与插件往往需要大量 `.rc` 配置才能接近现代 IDE 的输入体验。fish 把高亮、建议与补全作为默认能力，减少「换机器就要重装 Oh My Zsh 插件」的维护成本。对脚本作者，fish 仍可作为日常交互 Shell 使用，复杂自动化可继续交给 bash/sh；对新手，官方教程与 `help` 命令降低了 Shell 入门门槛。

## 与替代方案

- 相比 **[bash](https://www.gnu.org/software/bash/)**，fish 交互体验更现代（高亮、建议、补全开箱即用），但 **不是 POSIX 兼容 Shell**，部分 bash 脚本语法与变量展开行为不同，不适合作为系统 `/bin/sh` 或纯 bash 脚本的默认解释器。
- 相比 **[zsh](https://www.zsh.org/) + [Oh My Zsh](https://github.com/ohmyzsh/ohmyzsh)**，fish 零配置即可用，无需管理插件与主题仓库；zsh 生态更大、与 macOS 默认 Shell 迁移成本更低，且可通过插件复刻 fish 式体验。
- 相比 **[nushell](https://github.com/nushell/nushell)**，fish 更贴近传统 Unix 命令管道模型，学习曲线更缓；nushell 以结构化数据与表格输出见长，适合数据探索型工作流。
- 相比 **[Starship](https://starship.rs/)** 等跨 Shell 提示符，fish 提供完整 Shell 运行时而非仅美化提示符；若只需统一 bash/zsh/fish 的提示符样式，Starship 更轻量。
- **边界说明**：fish 默认不读取 `~/.bashrc` / `~/.zshrc`；与 bash 混用时可用 `bash script.sh` 显式调用；GPL-2.0 许可，嵌入闭源产品分发前需评估合规。

## 适应人群

- 日常在 macOS 或 Linux 终端工作、希望减少 Shell 配置时间的开发者与运维工程师。
- 刚接触命令行、需要直观反馈（高亮、建议、补全）的学习者。
- 已用 bash/zsh 但想单独保留一套「交互专用 Shell」、脚本仍用 bash 的混合工作流用户。

## 如何使用

### 前置条件

- 操作系统：macOS 10.12+、主流 Linux 发行版，或 Windows 10/11 下的 WSL / Cygwin / MSYS2。
- 运行 fish 需常见 Unix 工具（`mktemp` 及 coreutils 等）；可选功能依赖 `man`、Python 3.5+（补全生成与 `fish_config`）、剪贴板工具（`pbcopy`/`xclip`/`wl-copy` 等）。
- 若从源码构建：Rust 1.85+、CMake 3.15+、C 编译器；详见仓库 README。

### 安装方式

**macOS（Homebrew，推荐）：**

```bash
brew install fish
```

**Ubuntu / Debian（官方 PPA）：**

```bash
sudo apt-add-repository ppa:fish-shell/release-4
sudo apt update
sudo apt install fish
```

**Fedora / openSUSE 等**：可从 [openSUSE Build Service](https://software.opensuse.org/download.html?project=shells%3Afish%3Arelease%3A4&package=fish) 获取对应包，或访问 [fishshell.com](https://fishshell.com/) 下载安装包。

**安装后设为默认 Shell（可选）：**

```bash
# 将 fish 加入 /etc/shells（若尚未登记）
echo $(which fish) | sudo tee -a /etc/shells
chsh -s $(which fish)
```

### 首次运行

在当前终端中直接启动 fish 试用，无需切换默认 Shell：

```bash
fish
```

首次进入可运行 `help` 打开文档，或执行 `fish_config` 在浏览器中调整主题与快捷键。

### 验证是否成功

```bash
fish --version
echo $FISH_VERSION
```

应输出版本号（如 `fish, version 4.x.x`）。在 fish 内输入部分命令名，应看到语法高亮与灰色自动建议；按 Tab 应出现上下文补全。

### 常见坑 / 注意事项

- **非 POSIX Shell**：`for i in *.png; echo $i; done` 等 bash 一行写法在 fish 中语法不同；运行旧脚本请用 `bash script.sh` 或 `sh script.sh`。
- **环境变量**：fish 使用 `set -x NAME value` 而非 `export NAME=value`；从 bash 迁移时需改写 `.profile` 中的导出语句。
- **默认 Shell 切换**：`chsh` 后需重新登录；macOS 用户若用 Terminal.app，还可在「描述文件 → Shell」中单独指定 fish。
- **Windows 原生**：官方主要支持 WSL/Cygwin/MSYS2，无独立 Windows 原生 build；WSL 内按 Linux 发行版说明安装即可。
- **GPL 许可**：fish 主体为 GPL-2.0，商业嵌入或修改分发前请阅读 `COPYING` 与 `doc_src/license.rst`。

---

# Nginx Proxy Manager

> Docker 可视化管理 Nginx 反向代理与 Let's Encrypt 证书，Homelab 与家庭自托管的入口网关。

- 页面：https://www.niceshare.site/github/nginx-proxy-manager/
- 仓库：https://github.com/NginxProxyManager/nginx-proxy-manager
- 官网：https://nginxproxymanager.com
- 语言：TypeScript
- Stars：33460
- 许可证：MIT
- 标签：自托管、开发工具、自动化
- 收录：2026-07-03（更新于 2026-07-03）

## 项目介绍

Nginx Proxy Manager（NPM）把 Nginx 反向代理、SSL 终止与域名转发封装进预构建 Docker 镜像，并提供基于 Tabler 的 Web 管理界面。用户无需手写 Nginx 配置，即可为家中或内网运行的 Web 服务添加公网域名、自动申请 Let's Encrypt 证书，并管理重定向、TCP/UDP 流转发与访问控制。项目定位是「低门槛的 Homelab 入口网关」，高级 Nginx 选项对进阶用户仍可选开放。

## 核心特性

- **可视化代理主机**：通过表单创建转发域名、重定向、Stream 与 404 主机，无需了解 Nginx 语法
- **免费 SSL**：集成 Let's Encrypt 自动续期，也支持上传自定义证书
- **访问控制**：Access List 与基础 HTTP 认证，可按主机限制访问
- **用户与审计**：多用户管理、权限分级与操作审计日志
- **进阶可扩展**：超级用户可编辑自定义 Nginx 配置片段，满足特殊路由需求

## 对用户价值

自托管 Immich、Home Assistant、NAS 面板等服务时，往往要面对「每个应用各自配 HTTPS」「路由器端口转发复杂」「证书续期麻烦」等问题。NPM 把 80/443 入口收敛到单一容器：在管理面板里填域名与内网 IP:端口，即可自动完成反向代理与证书签发，相当于为整个家庭网络提供统一的 TLS 网关。对不熟悉 Nginx 的用户，它把数小时的学习成本压缩到几分钟的表单操作。

## 与替代方案

- 相比 **手写 Nginx**，NPM 上手更快、证书自动化更省心；但复杂 location 规则、性能调优仍建议直接编辑 Nginx 配置。
- 相比 **Caddy**，NPM 提供完整 GUI 与多用户管理，适合「多人共用 Homelab 面板」；Caddy 配置即代码、自动 HTTPS 更简洁，但缺少同等粒度的 Web 管理体验。
- 相比 **Traefik**，NPM 更偏传统「域名 → 内网 IP」静态路由，与 Docker 标签/服务发现集成较弱；Traefik 适合 Kubernetes 或动态容器编排场景。
- 相比 **SWAG**（LinuxServer.io）等同类型 Docker 反代套件，NPM 界面更现代、社区体量更大（3 万+ Star），功能侧重 HTTP/HTTPS 主机与 Stream，而非媒体服务器专用集成。

## 适应人群

- 在家庭宽带或 VPS 上自托管多个 Web 服务，需要统一 HTTPS 入口的 Homelab 爱好者。
- 不想深入学习 Nginx 配置，但希望用域名访问内网应用的开发者与运维新手。
- 小团队需要为内部工具快速上线反向代理、访问控制与证书管理的效率型用户。

## 如何使用

### 前置条件

- 已安装 [Docker](https://docs.docker.com/install/) 与 Docker Compose 插件。
- 若需公网访问：路由器已配置 80/443 端口转发至运行 NPM 的主机，域名 DNS 已指向公网 IP（可用 DuckDNS、Cloudflare DDNS 等动态域名服务）。
- 默认使用容器内 SQLite；大规模或多实例部署可选 MySQL/MariaDB 或 Postgres（见[官方完整部署文档](https://nginxproxymanager.com/setup/)）。

### 安装方式

创建 `docker-compose.yml`（最小可用配置）：

```yaml
services:
  app:
    image: 'docker.io/jc21/nginx-proxy-manager:latest'
    restart: unless-stopped
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
```

启动：

```bash
docker compose up -d
```

生产环境建议固定镜像标签（如 `jc21/nginx-proxy-manager:2.15.1`）并设置 `TZ` 时区；MySQL/Postgres 与 ARM 设备说明见[官方 Setup 指南](https://nginxproxymanager.com/setup/)。

### 首次运行

容器首次启动会生成 JWT 密钥、初始化数据库并创建默认管理员，可能需要等待数分钟（取决于主机熵池与磁盘速度）。

浏览器访问管理界面（默认端口 **81**）：

```
http://127.0.0.1:81
```

使用默认凭据登录（**首次登录后系统会强制修改**）：

- 邮箱：`admin@example.com`
- 密码：`changeme`

登录后在面板中添加 **Proxy Host**：填写域名、转发目标（内网 IP 与端口），开启 SSL 并选择「Request a new SSL Certificate」即可自动申请 Let's Encrypt 证书。

### 验证是否成功

- 管理界面 `http://<主机IP>:81` 可正常登录，且已修改默认密码。
- 添加测试 Proxy Host 后，通过配置的域名可访问后端服务。
- 若启用 SSL，浏览器地址栏显示有效 HTTPS 锁标，证书颁发者为 Let's Encrypt。
- `docker compose ps` 显示 `app` 容器状态为 `running`，`./data` 与 `./letsencrypt` 目录已生成持久化文件。

### 常见坑 / 注意事项

- **端口 81 勿暴露公网**：管理面板默认监听 81，仅应在内网或 VPN 访问；公网只需开放 80/443。
- **Let's Encrypt 需可达 80 端口**：证书申请依赖 HTTP-01 验证，确保域名解析正确且防火墙/路由器已放行 80。
- **armv7 已弃用**：2.14+ 不再支持 armhf，旧树莓派等设备需使用 `2.13.7` 镜像标签。
- **ACL 与后端登录冲突**：对 Proxy Host 启用 HTTP 基础认证后，可能与后端应用自身的登录机制冲突（浏览器只能维护一套 Authorization 头），需二选一或调整应用鉴权方式。
- **数据备份**：`./data` 含 SQLite 数据库与 JWT 密钥，`./letsencrypt` 含证书；升级或迁移前务必备份这两个卷。

---

# ZeroClaw

> Rust 单二进制自托管 AI Agent 运行时，多频道多模型，数据与密钥留在本机。

- 页面：https://www.niceshare.site/github/zeroclaw/
- 仓库：https://github.com/zeroclaw-labs/zeroclaw
- 官网：https://www.zeroclawlabs.ai/
- 语言：Rust
- Stars：32117
- 许可证：Apache-2.0
- 标签：Agent、本地模型、开发工具
- 收录：2026-07-03（更新于 2026-07-03）

## 项目介绍

ZeroClaw 是一款用 **Rust 编写的个人 AI Agent 运行时**：单个二进制文件即可配置并运行，对接 Anthropic、OpenAI、Ollama 等约 20 家 LLM 提供商，通过 Discord、Telegram、Matrix、邮件、语音、Webhook、CLI 等 30+ 频道触达用户，并借助 shell、浏览器、HTTP、硬件与自定义 MCP 等工具执行动作。核心理念是**你拥有 Agent、数据与运行机器**——密钥与 workspace 均留在本地，适合希望自托管、可审计、可深度定制的开发者与进阶用户。

## 核心特性

- **多频道统一 Agent 循环**：Discord、Telegram、Matrix、邮件、Webhook、CLI 等入站消息汇聚到同一 Agent，配置见 `[channels.<type>.<alias>]`
- **Provider 无关与路由**：`[providers.models.<type>.<alias>]` 统一 schema，支持 fallback 链与 OpenAI 兼容端点
- **安全优先 + 可控放权**：默认 `supervised` 自治级别，中风险需审批、高风险阻断；支持 Landlock / Bubblewrap / Seatbelt / Docker 沙箱与加密 tool receipts
- **Gateway 与 Dashboard**：HTTP/WebSocket 网关，Web 面板可聊天、浏览记忆、编辑配置、管理 cron 与检视工具调用
- **SOP 引擎**：MQTT / Webhook / cron / 外设事件触发的标准作业流程，带审批门与可恢复运行
- **硬件与外设**：通过 `Peripheral` trait 支持 Raspberry Pi、STM32、Arduino、ESP32 的 GPIO / I2C / SPI / USB
- **ACP 集成**：Agent Client Protocol（JSON-RPC 2.0 over stdio）对接 IDE / 编辑器

## 对用户价值

不想依赖 Node 生态或云端托管、又 snapshot 级部署（预编译二进制数秒安装）的用户，可以用 ZeroClaw 在 Linux、macOS、Windows、FreeBSD、NixOS 或容器里跑常驻助手。Provider 路由与本地 Ollama 支持让**离线或混合云**场景更灵活；SOP 与硬件能力则适合自动化运维、IoT 与边缘设备。相比「聊天网页 + API Key」，ZeroClaw 把频道、工具、记忆与策略收进一份 TOML 配置，便于版本管理与审计。

## 与替代方案

- 相比 [OpenClaw](https://github.com/openclaw/openclaw)（TypeScript Gateway 生态、伴侣应用与 Canvas/语音节点），ZeroClaw 走 **Rust 单二进制、feature 裁剪与 minimal preset（约 6.6 MB）** 路线，强调运行时体积、安全策略与硬件/SOP；二者定位相近但技术栈与扩展方式不同，可按团队语言偏好与部署约束选型。
- 相比 [Hermes Agent](https://github.com/NousResearch/hermes-agent) 等强调**自进化技能与跨会话记忆**的方案，ZeroClaw 更侧重**多频道运行时、Gateway Dashboard 与 SOP/硬件编排**，而非技能 marketplace 叙事。
- 相比 [Cline](https://github.com/cline/cline)、[Aider](https://github.com/Aider-AI/aider) 等 **IDE 结对编程**工具，ZeroClaw 是**生活与工作流助理运行时**，主战场是消息频道、cron、浏览器与 shell 工具，ACP 仅作为频道之一。
- 相比 [Dify](https://github.com/langgenius/dify)、[n8n](https://github.com/n8n-io/n8n) 等**可视化工作流平台**，ZeroClaw 是**单人 Agent 运行时**，以 TOML 配置与 CLI 为主，不适合多租户 SaaS 或拖拽式编排。
- 开发机可启用 [YOLO mode](https://docs.zeroclawlabs.ai/master/en/getting-started/yolo.html) 跳过部分安全门；生产或公网暴露 Gateway 前务必阅读官方 Security 文档，勿默认裸奔。

## 适应人群

- 偏好 **Rust、单二进制、可裁剪 feature** 的自托管 AI 助手用户。
- 需要 **Ollama 本地模型 + 多 IM 频道** 统一入口的开发者。
- 想探索 **GPIO / 嵌入式硬件、SOP 自动化** 与 Agent 结合的极客与创客。
- 从 OpenClaw 等方案迁移、评估 **更轻运行时或更强沙箱策略** 的技术用户。

## 如何使用

### 前置条件

- **操作系统**：Linux、macOS、Windows、FreeBSD、NixOS 或 Docker；各平台细节见 [官方 Setup 文档](https://docs.zeroclawlabs.ai/master/en/setup/linux.html)。
- **模型访问**：至少配置一个 provider（Anthropic、OpenAI、Ollama 等）；V3 配置最少需 provider、agent、risk profile 四段式结构，见 [Provider Configuration](https://docs.zeroclawlabs.ai/master/en/providers/configuration.html)。
- **源码构建**（可选）：需安装 Rust toolchain；可用 `./install.sh --list-features` 查看 feature 列表。
- 接入真实消息频道前，阅读 [Security overview](https://docs.zeroclawlabs.ai/master/en/security/overview.html)；默认 supervised 模式，中高风险操作需审批。

### 安装方式

一键安装（安装脚本会询问预编译或源码构建）：

```bash
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
```

或克隆后本地安装：

```bash
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh
```

常用 flags：

```bash
./install.sh --prebuilt              # 强制预编译二进制
./install.sh --source                # 强制源码构建
./install.sh --preset minimal        # 最小 kernel preset（约 6.6 MB）
./install.sh --skip-quickstart         # 仅安装，稍后手动 quickstart
./install.sh --dry-run --prebuilt    # 预览安装步骤
```

### 首次运行

安装完成后通常会自动进入 quickstart；也可手动：

```bash
zeroclaw quickstart               # 一次性向导：选 provider、生成可用 config
zeroclaw agent -a <alias>         # 使用 [agents.<alias>] 交互对话
zeroclaw service install          # 注册 systemd / launchctl / Windows Service
zeroclaw service start            # 后台常驻运行
```

配置文件位于 `~/.zeroclaw/config.toml`。完整 walkthrough 见 [Quick start](https://docs.zeroclawlabs.ai/master/en/getting-started/quickstart.html)。

### 验证是否成功

- `zeroclaw agent -a <alias>` 能收到合理回复。
- `zeroclaw auth status` 显示 provider 认证正常（OpenAI Codex 订阅等场景尤其重要）。
- 若已安装服务：`zeroclaw service` 相关命令显示运行中；Gateway/Dashboard 可按文档启用并访问。
- 配置频道后，从 Discord/Telegram 等发送测试消息，确认入站路由到 Agent 循环。

### 常见坑 / 注意事项

- **官方仓库唯一**：仅 `zeroclaw-labs/zeroclaw` 为官方源；留意仿冒仓库与域名（README 有 impersonation 声明）。
- **OpenAI Codex 订阅**：标准订阅走 stored auth profiles，不必在 provider 条目写 `api_key`；自定义兼容网关才需显式 `api_key` / `uri`。
- 若日志出现 `provider streaming failed, falling back to non-streaming chat`，ZeroClaw 会自动重试非流式；先查 `zeroclaw auth status` 再改配置。
- **YOLO mode** 仅适合可信开发机；生产环境保持 supervised 与沙箱策略。
- 安全漏洞勿公开 issue，应邮件 `security@zeroclaw.dev`；升级前查阅 [Releases](https://github.com/zeroclaw-labs/zeroclaw/releases) 与 CHANGELOG。

---

# nginx

> 全球最流行的开源 Web 服务器与反向代理，兼具高性能负载均衡、API 网关与内容缓存能力。

- 页面：https://www.niceshare.site/github/nginx/
- 仓库：https://github.com/nginx/nginx
- 官网：https://nginx.org/
- 语言：C
- Stars：30938
- 许可证：BSD-2-Clause
- 标签：开发工具、自动化、CLI
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

NGINX（读作「engine x」）是全球使用最广泛的开源 Web 服务器之一，同时承担反向代理、负载均衡、API 网关与内容缓存等角色。项目采用 master/worker 多进程架构，以事件驱动与低内存占用著称，适合高并发 HTTP/HTTPS、TCP/UDP 代理与邮件代理场景。官方建议优先使用 [nginx.org](https://nginx.org/) 发布的二进制包或本仓库源码，而非发行版自带的旧版社区包，以获取最新特性与安全修复。

## 核心特性

- **模块化架构**：核心功能由静态或动态模块扩展，可用 `nginx -V` 查看当前二进制内置模块
- **声明式配置**：通过文本配置文件与指令（directives）组合 server/location/upstream 等结构，灵活度高
- **多进程运行时**：master 进程管理 worker 与配置热加载，worker 数量可固定或按 CPU 核数自动调整
- **稳定版与主线版**：stable 仅合入关键修复，mainline 承载最新特性；可按环境选择发布线
- **动态模块支持**：如 njs（JavaScript 扩展）等可在不重新编译核心的情况下按需加载

## 对用户价值

NGINX 把静态资源托管、反向代理、七层负载均衡、限流、TLS 终止与边缘缓存收敛到单一、轻量的进程模型中，在同等硬件上往往比传统多线程服务器承受更高并发。对团队而言，它既是入门自建站点的默认选择，也是 Kubernetes Ingress、微服务网关与 CDN 边缘节点的常见底层组件。BSD 2-Clause 许可也便于商业部署与二次集成。

## 与替代方案

- 相比 **Apache HTTP Server**，NGINX 事件驱动模型在高并发静态与代理场景通常更省内存；Apache 的 `.htaccess` 与模块生态在共享主机与传统 LAMP 栈中仍常见。
- 相比 **Caddy**，NGINX 配置更显式、模块与运维实践更成熟，但自动 HTTPS 与配置简洁度上 Caddy 对新手更友好。
- 相比 **Traefik**，NGINX 更偏通用 Web/代理引擎，需手写配置；Traefik 与容器编排、服务发现集成更深，适合云原生动态路由。
- 相比 **HAProxy**，两者都可做负载均衡；HAProxy 专注四层/七层 LB 与精细流量调度，NGINX 则同时覆盖 Web 服务、缓存与丰富 HTTP 模块。

## 适应人群

- 需要自建网站、API 网关或内网反向代理的后端与全栈开发者。
- 负责生产环境入口流量、TLS、限流与缓存策略的运维与 SRE 工程师。
- 评估 Ingress、边缘节点或高性能 HTTP 基础设施的技术负责人与架构师。

## 如何使用

### 前置条件

- Linux、FreeBSD 或 macOS 等受支持平台；Windows 版目前为概念验证，仅建议开发测试使用。
- 生产环境优先通过官方包仓库安装，需 root 或 sudo 权限管理系统服务。
- 若从源码构建，需 GCC、make 及 PCRE、zlib 等依赖；启用 TLS 时还需 OpenSSL 开发库。

### 安装方式

**Linux（推荐：官方预编译包）**

按发行版添加 [nginx.org 官方仓库](https://nginx.org/en/linux_packages.html) 后安装，例如 Debian/Ubuntu：

```bash
# 示例：按官方文档添加 nginx.org 源并安装 stable 或 mainline 包
sudo apt update
sudo apt install nginx
```

**从源码构建（本仓库）**

```bash
sudo apt update
sudo apt install gcc make libpcre3-dev zlib1g-dev libssl-dev
git clone https://github.com/nginx/nginx.git
cd nginx
auto/configure
make
sudo make install
```

默认安装路径为 `/usr/local/nginx/`。更多构建选项见 [configure 文档](https://nginx.org/en/docs/configure.html)。

### 首次运行

**包管理器安装后：**

```bash
sudo systemctl start nginx    # 或 service nginx start
```

**源码安装后：**

```bash
sudo /usr/local/nginx/sbin/nginx
```

编辑站点配置（包安装常见路径为 `/etc/nginx/nginx.conf`），重载配置：

```bash
sudo nginx -t && sudo nginx -s reload
```

新手可从 [Beginner's Guide](https://nginx.org/en/docs/beginners_guide.html) 入手，逐步配置 server、location 与 upstream。

### 验证是否成功

```bash
curl localhost
```

若返回以 `Welcome to nginx!` 开头的 HTML 页面，说明服务已正常监听。也可执行 `nginx -v` 查看版本，`nginx -V` 查看编译参数与内置模块。

### 常见坑 / 注意事项

- **勿用发行版旧包**：系统自带 nginx 往往版本滞后；生产环境应使用 nginx.org 官方包或自行跟踪本仓库发布。
- **stable 与 mainline**：需要新特性（如 HTTP/3）可选 mainline；保守生产环境常用 stable，升级前阅读 [CHANGES](https://nginx.org/en/CHANGES)。
- **配置语法严格**：`nginx -t` 通过后再 reload，避免错误配置导致服务无法启动。
- **共享内存与限流**：限流、缓存等模块常需 `limit_req_zone` 等共享内存区，worker 间才能一致计数。
- **Windows 限制**：官方明确 Windows 构建不适合生产；生产请使用 Linux/FreeBSD 等成熟路径。

---

# Claude Code Plugins Official

> Anthropic 官方 Claude Code 插件市场，汇集内外部高质量插件与 Skill 包。

- 页面：https://www.niceshare.site/github/claude-plugins-official/
- 仓库：https://github.com/anthropics/claude-plugins-official
- 官网：https://code.claude.com/docs/en/plugins
- 语言：Python
- Stars：30752
- 许可证：Apache-2.0
- 标签：AI 编程、Agent、开发工具
- 收录：2026-06-24（更新于 2026-06-24）

## 项目介绍

这是 Anthropic 维护的 **Claude Code 官方插件目录**：仓库收录经筛选的内部插件（`/plugins`）与合作伙伴、社区提交的外部插件（`/external_plugins`），并通过 Claude Code 内置的 `/plugin` 市场机制一键分发。每个插件可包含 Slash 命令、Agent 定义、Skills、MCP 服务器配置等能力模块，是扩展 Claude Code 工作流的首选官方入口。

## 核心特性

- **双轨插件来源**：`/plugins` 由 Anthropic 团队维护（如 code-review、feature-dev、security-guidance、hookify）；`/external_plugins` 收录 GitHub、Playwright、Linear 等第三方集成
- **标准插件结构**：`.claude-plugin/plugin.json` 元数据，可选 `commands/`、`agents/`、`skills/`、`.mcp.json` 等目录
- **Skill-bundle 支持**：无完整 manifest 的远程技能包可通过 `strict: false` 与 `skills` 数组声明，从 Git 子目录拉取 `SKILL.md`
- **内置市场安装**：在 Claude Code 中通过 `/plugin install {name}@claude-plugins-official` 或 `/plugin > Discover` 浏览安装
- **LSP 与 MCP 生态**：涵盖多语言 LSP（TypeScript、Rust、Python 等）与 MCP 开发、隧道等工具向插件
- **外部提交通道**：合作伙伴可通过 [插件目录提交表单](https://clau.de/plugin-directory-submission) 申请上架

## 对用户价值

自行拼装 MCP 服务器、Skills 与命令脚本成本高且难维护。官方目录把常用能力打包成可版本化、可审查的插件单元，降低「从零配置 Claude Code 扩展」的门槛。内部插件代表 Anthropic 推荐实践（代码审查、安全指引、会话报告等），外部插件则连接 GitHub、GitLab、Firebase 等日常工具链，让 Agent 在终端内直接触达团队已有系统。

## 与替代方案

- 相比 [claude-code](https://github.com/anthropics/claude-code) 仓库内嵌的 `plugins/`，本目录是 **独立、可扩展的官方市场源**，并包含第三方合作伙伴插件。
- 相比 [anthropics/skills](https://github.com/anthropics/skills) 技能仓库，本目录覆盖 **完整插件形态**（命令、Agent、MCP、LSP），不仅限于 `SKILL.md` 技能包。
- 相比手动克隆插件仓库或自建 marketplace JSON，使用 `@claude-plugins-official` 可获得 **统一命名空间与发现入口**，但插件内容由各作者维护，安装前仍需自行评估信任边界。
- 若只需单一 MCP 工具，直接配置 `.mcp.json` 可能更轻；需要成套工作流时再选目录内插件。

## 适应人群

- 已使用 Claude Code，希望快速安装代码审查、LSP、MCP 等官方推荐扩展的开发者。
- 需要将 GitHub、Linear、Playwright 等第三方服务接入 Claude Code 工作流的工程师。
- 计划向官方市场上架插件的合作伙伴或团队维护者。

## 如何使用

### 前置条件

- 已安装并可正常启动 [Claude Code](https://github.com/anthropics/claude-code) CLI。
- 理解官方免责声明：Anthropic 不控制插件内 MCP 服务器与外部软件行为，安装前请确认来源可信。
- 查阅各插件子目录 `README.md` 了解额外依赖（如语言运行时、API 密钥）。

### 安装方式

在 Claude Code 会话中安装指定插件（将 `{plugin-name}` 替换为目录名，如 `code-review`）：

```
/plugin install {plugin-name}@claude-plugins-official
```

或在 Claude Code 内打开 **`/plugin > Discover`** 浏览官方市场并选择安装。

浏览可用插件可克隆本仓库查看 `plugins/` 与 `external_plugins/` 目录列表，或参阅 [官方插件文档](https://code.claude.com/docs/en/plugins)。

### 首次运行

安装完成后，根据插件类型尝试对应入口：Slash 命令（如 `/code-review`）、自动触发的 Agent 或 Skills，或插件 README 中说明的 MCP 能力。建议先在一个测试项目中安装单个插件，确认行为符合预期再纳入日常流程。

### 验证是否成功

在 `/plugin` 列表中应能看到已安装的 `@claude-plugins-official` 插件。尝试执行该插件文档中的示例命令或对话触发语，确认无配置错误；若插件依赖 MCP，检查 `.mcp.json` 所需环境变量与网络可达性。

### 常见坑 / 注意事项

- **信任边界**：外部插件可能包含任意 MCP 服务器与脚本，务必阅读各插件 homepage 与许可信息后再用于生产代码库。
- **许可证分散**：仓库根目录为 Apache-2.0，但各链接插件可能有独立 LICENSE，商用前需逐插件核对。
- **Skill-bundle 插件**需正确配置 `source`（git-subdir、ref、sha）与 `skills` 路径，否则 Claude Code 无法加载远程 `SKILL.md`。
- 外部插件上架需通过官方审核；自研插件可参考 `plugins/example-plugin` 与 [plugin-dev](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/plugin-dev) 学习结构，不一定从此市场分发。

---

# OmniRoute

> MIT 开源本地 AI 网关：单端点聚合 250+ 提供商与免费额度，配额感知回退，兼容主流编程 Agent。

- 页面：https://www.niceshare.site/github/omniroute/
- 仓库：https://github.com/diegosouzapw/OmniRoute
- 官网：https://omniroute.online
- 语言：TypeScript
- Stars：29696
- 许可证：MIT
- 标签：AI 编程、开发工具、CLI
- 收录：2026-07-25（更新于 2026-07-25）

## 项目介绍

OmniRoute 是一款 **MIT 开源、本地优先的 AI 网关**：把 Claude Code、Codex、Cursor、Cline、Copilot、OpenCode 等工具统一指向一个 OpenAI 兼容端点（默认 `http://localhost:20128/v1`），由网关在 250+ 提供商（含 90+ 免费档）间做配额感知路由与自动回退。它强调「零起步成本」——聚合文档化的免费额度并在仪表盘展示，同时用 RTK + Caveman 压缩降低 tool-heavy 会话的 token 消耗。请求路径跑在你自己的机器上，不经过 OmniRoute 云。

## 核心特性

- **单端点多协议**：OpenAI ↔ Claude ↔ Gemini ↔ Responses API 互译，多数编程 Agent 只需改 Base URL
- **配额感知自动回退**：订阅 → API → 低价 → 免费等多层策略，额度耗尽时毫秒级切换，减少中断
- **RTK + Caveman 压缩**：对 git diff、grep、日志等工具输出做堆叠压缩，官方称可节省约 15–95% 相关 token
- **内置 MCP / A2A**：MCP 工具集、A2A 协议与记忆、护栏等生产向能力
- **多端运行**：npm / Docker / Electron 桌面 / Termux / PWA，密钥本地 AES-256-GCM 加密，默认定制无遥测

## 对用户价值

手工堆叠各家免费档要维护多套 SDK、密钥与限流，很难知道「这个月还剩多少」。OmniRoute 把分散额度收成一个本地仪表盘，并把 Claude Code、Cursor 等工具接到同一代理，避免每个 IDE 单独配一套模型账号。额度打满或限流时自动换下一家，适合长期结对编程又不想被单点配额卡死的场景。压缩链路则针对工具输出浪费 token 的痛点，让同等预算能跑更长会话。

## 与替代方案

- 相比 [OpenRouter](https://openrouter.ai/) 等**托管聚合 API**：OmniRoute 是**自托管本地代理**，密钥与流量留在本机；OpenRouter 免运维但走第三方云，计费与隐私模型不同。
- 相比 [LiteLLM](https://github.com/BerriAI/litellm) 等**通用 LLM 代理库**：LiteLLM 偏服务端/SDK 集成与统一调用；OmniRoute 更面向**编程 Agent 一键接入、免费档聚合、仪表盘与压缩**，开箱体验更偏「个人/小团队网关」。
- 相比只改某个 CLI 的 router（如 Claude Code 专用路由）：OmniRoute 目标是**一套配置服务多种工具**；若你只固定用单一 CLI，专用方案可能更轻，但跨 Cursor / Cline / Codex 时 OmniRoute 更省事。
- 官方对比文档见仓库 [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)；提供商数量与免费额度会随社区更新，以 README 与仪表盘为准。

## 适应人群

- 同时使用 **Claude Code、Cursor、Cline、Codex** 等工具，想用**一个本地端点**统一模型与回退策略的开发者。
- 希望尽量用 **免费档 / 订阅额度** 做日常编程，并需要额度可视与自动切换的个人用户。
- 需要 **Docker / 桌面 / Termux** 自托管、关心密钥不出本机的隐私敏感用户。

## 如何使用

### 前置条件

- **Node.js** 环境（全局 npm/pnpm 安装），或 Docker。
- 至少准备一个提供商账号或免费档（如 README 提到的 Kiro AI、OpenCode Free 等；具体以仪表盘 Providers 列表为准）。
- 了解 MIT 许可与各上游提供商的服务条款；免费额度统计方法见官方 [FREE_TIERS](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/FREE_TIERS.md)。

### 安装方式

全局安装（官方 Quick Start）：

```bash
npm install -g omniroute
omniroute
```

Docker：

```bash
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -p 20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
```

源码开发：

```bash
cp .env.example .env && npm install
PORT=20128 npm run dev
```

仪表盘默认 `http://localhost:20128`，API 为 `http://localhost:20128/v1`。更多路径见 [Docker Guide](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/DOCKER_GUIDE.md)、[Setup Guide](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/SETUP_GUIDE.md)。

### 首次运行

1. 启动后打开仪表盘 → **Providers**，连接至少一个免费或付费提供商。
2. 在 **Endpoints** 复制本地 API Key。
3. 将编程工具指向 OmniRoute：

```txt
Base URL: http://localhost:20128/v1
API Key:  <Dashboard → Endpoints 中复制>
Model:    auto
```

各 CLI 的详细配置见 [CLI Tools Guide](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/CLI-TOOLS.md)。

### 验证是否成功

```bash
curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"
```

应返回已连接模型列表。再在 Claude Code / Cursor 等工具发一条简单请求，确认路由与回退按预期工作。

### 常见坑 / 注意事项

- **提供商条款与额度**：免费档数量与「约 1.6B tokens/月」等汇总数字会变化，且依赖各家政策；以仪表盘与 [FREE_TIERS](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/FREE_TIERS.md) 方法论为准，勿当作 SLA。
- **密钥安全**：API Key / OAuth 存在本地；勿把 `.env` 或数据卷提交到公开仓库。远程暴露网关前先读授权与护栏文档。
- **安装体积**：`better-sqlite3` 等原生依赖可能触发 postinstall；CI 可用 `OMNIROUTE_SKIP_POSTINSTALL=1`（见 README）。
- **压缩效果因场景而异**：官方节省比例主要针对 tool-heavy 会话中的合格 token，非所有请求一律打折。
- 升级前阅读 Releases；多平台部署差异见 Termux / PWA / Electron 相关指南。

---

# ppt-master

> 用 AI 从任意文档生成原生可编辑 PowerPoint，支持模板复用、动画与旁白。

- 页面：https://www.niceshare.site/github/ppt-master/
- 仓库：https://github.com/hugohe3/ppt-master
- 官网：https://hugohe3.github.io/ppt-master/
- 语言：Python
- Stars：29341
- 许可证：MIT
- 标签：AI 编程、工作流、自动化
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

PPT Master 是 Hugo He 开源的 **AI 演示文稿生成工作流（Skill）**：在 Claude Code、Cursor、VS Code Copilot 等 Agent IDE 里对话，即可把 PDF、DOCX、图片或粘贴文本转成 **原生 DrawingML 形状** 的可编辑 `.pptx`，而非每页一张大图。项目以 Python 脚本负责 SVG 生成、PPTX 导出、图片检索与旁白合成；模型负责内容分析与视觉设计。除 16:9 幻灯片外，还支持小红书、公众号等十余种画布格式。

## 核心特性

- **真 PowerPoint**：输出可在 PowerPoint / Keynote / WPS 中逐元素点击编辑的形状、文本框与图表，带原生翻页过渡与入场动画
- **任意素材输入**：支持 PDF、DOCX、Markdown、网页、图片或聊天粘贴；也可把既有 `.pptx` 当模板填充或风格参考
- **本地流水线**：除调用 AI 模型外，生成与导出在本地完成，无需把源文件上传到第三方 PPT 平台
- **实时预览与可视化微调**：生成时在 `localhost:5050` 浏览器预览，可拖拽改字色字号，或标注后让 AI 重写区域
- **旁白与视频**：可将演讲备注转为逐页语音（默认 edge-tts），嵌入 PPTX 后由 PowerPoint 导出带同步旁白的 MP4
- **多模型与多宿主**：推荐 Claude Opus + `gpt-image-2` 达质量上限；亦支持 GPT、Gemini、Kimi 等；可通过 `npx skills add` 或 Claude 插件市场安装

## 对用户价值

多数 AI 演示工具输出的是「每页一张图」或网页 Deck，进 PowerPoint 后几乎无法改稿。PPT Master 瞄准 **可继续打磨的原生 PPTX**：把内容分析、版式、配图、动画、导出拆成可复用工作流，让你用对话完成 80% 体力活，再在 Office 里精修。成本仅模型用量，无额外 PPT 订阅；对经常做汇报、路演、培训课件但不想被 SaaS 锁定的职场人，它把「Agent + Python」落到一件具体可交付的事上。

## 与替代方案

- 相比 **Gamma、Beautiful.ai、Tome** 等在线 AI PPT SaaS，PPT Master **不上传源文件到其服务器**，输出是本地 `.pptx` 而非托管网页；你需要自备 Agent IDE 与模型 API，学习曲线更高，但无平台锁定。
- 相比 **Microsoft Copilot for PowerPoint**，Copilot 深度集成 Office 订阅生态；PPT Master 是开源 Harness，可在 Cursor / Claude Code 等环境运行，并支持自定义模板、旁白克隆与 SVG 级视觉风格（见官方 six-style 示例）。
- 相比 **把 HTML/Reveal.js 当演示稿**，PPT Master 专注 **PPTX 交付物**；若团队只接受网页演示或只需模板填空，应选更轻量的路线。
- 作者强调这是 **工具而非许愿池**：模型越便宜，人工打磨越多；质量上限由模型（尤其长上下文 Claude + 图像生成）决定，而非脚本本身。

## 适应人群

- 咨询、投资、产品、培训等需要频繁做 Deck，且必须在 PowerPoint 里二次编辑的职场用户。
- 已在用 Claude Code、Cursor、Cline 等 Agent，想把「做 PPT」固化成可重复 Skill 的开发者。
- 重视数据留在本地、愿为可编辑交付物支付模型费用而非 PPT 月费的技术型用户。

## 如何使用

### 前置条件

- **Python 3.10+**（唯一硬性系统依赖）
- 具备读写文件、执行命令、多轮对话能力的 **Agent 宿主**（Cursor、Claude Code、VS Code + Copilot、Cline 等）
- 可访问的 **大模型 API**（质量优先：Claude Opus + `gpt-image-2`；性价比可试 Gemini 3.5 Flash）
- 可选：Pexels / Pixabay API Key（提升配图质量）；ElevenLabs 等（语音克隆旁白）
- Windows 用户建议先读官方 [Windows 安装指南](https://github.com/hugohe3/ppt-master/blob/main/docs/windows-installation.md)

### 安装方式

**方式 A — Git 克隆（完整仓库）**

```bash
git clone https://github.com/hugohe3/ppt-master.git
cd ppt-master
pip install -r requirements.txt
```

**方式 B — 技能市场（仅 Skill 文件，仍需 pip 安装脚本依赖）**

```bash
npx skills add hugohe3/ppt-master
# 在安装目录执行：pip install -r requirements.txt
```

Claude Code 内也可：

```bash
/plugin marketplace add hugohe3/ppt-master
/plugin install ppt-master@ppt-master
```

**方式 C — 下载 ZIP**：在 GitHub 页面 Code → Download ZIP，解压后同样执行 `pip install -r requirements.txt`。

旧版 `.doc` / `.odt` 等格式需额外安装 Pandoc；`.docx` / `.html` / `.epub` 等由 Python 原生处理。

### 首次运行

1. 将 PDF、DOCX 等素材放入 `projects/` 目录（或准备在聊天中直接粘贴文本）。
2. 在 Agent 对话中说明需求，例如：

```text
请根据 projects/q3-report/sources/report.pdf 做一份 PPT
```

3. AI 会先确认设计规格（模板、画幅、页数等），随后自动完成分析、配图、SVG 与导出。
4. 生成过程中可打开 `http://localhost:5050` 查看实时预览并做可视化微调。
5. 成品位于 `exports/<name>_<timestamp>.pptx`；`svg_output/` 会备份到 `backup/<timestamp>/` 便于重导出。

若需配图 API，可复制环境变量：

```bash
cp .env.example .env
# 或技能安装场景：
mkdir -p ~/.ppt-master && cp .env.example ~/.ppt-master/.env
```

### 验证是否成功

- 用 PowerPoint 或 WPS 打开 `exports/` 下最新 `.pptx`，确认元素可单独选中编辑（非整页图片）。
- 浏览 [官方示例](https://hugohe3.github.io/ppt-master/) 或 `examples/` 目录，对比版式与动画是否符合预期。
- 运行 `python3 skills/ppt-master/scripts/image_gen.py --list-backends` 检查图像后端是否配置正确（若使用 AI 生图）。

### 常见坑 / 注意事项

- **别指望一键完美**：README 明确这是 Harness，`harness + model = agent`；结果不满意先换更强模型，而非归咎于工具。
- **AI 跑偏时**：让它重读 `skills/ppt-master/SKILL.md`；复杂问题查 [FAQ](https://github.com/hugohe3/ppt-master/blob/main/docs/faq.md)。
- **复用既有 PPT 模板**：需明确说「用 template-fill 填充这份 pptx」或走 `/create-template` 流程，否则 AI 默认自由设计。
- **技能市场安装**：只拉取 Skill 文件，必须在安装路径执行 `pip install -r requirements.txt`，否则后处理脚本无法运行。
- **许可证**：MIT 开源；商用与模型 API 费用、配图版权（CC 署名等）需自行合规。

---

# Headless UI

> 无样式、全可访问的 React/Vue 组件库，专注交互逻辑与键盘导航，与 Tailwind CSS 深度配合定制界面。

- 页面：https://www.niceshare.site/github/headlessui/
- 仓库：https://github.com/tailwindlabs/headlessui
- 官网：https://headlessui.com
- 语言：TypeScript
- Stars：28627
- 许可证：MIT
- 标签：开发工具、前端、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Headless UI 是由 [Tailwind Labs](https://tailwindlabs.com) 维护的无样式（headless）UI 组件库，提供 React（`@headlessui/react`）与 Vue（`@headlessui/vue`）两套实现。组件只负责焦点管理、键盘导航、ARIA 属性与开关状态等交互逻辑，不附带任何预设 CSS，便于你用 Tailwind CSS 或自有设计系统完全定制外观。完整文档与示例见 [headlessui.com](https://headlessui.com)；本仓库为 monorepo 源码，日常集成通过 npm 安装对应包即可。

## 核心特性

- **完全无样式**：Dialog、Menu、Listbox、Combobox、Tabs、Popover 等组件零默认皮肤，样式 100% 由你控制
- **内置无障碍与键盘支持**：自动处理焦点陷阱、Esc 关闭、方向键导航、`aria-*` 属性，降低 a11y 实现成本
- **状态暴露清晰**：通过 `data-*` 属性（如 `data-open`、`data-focus`）与 render props 暴露 active/focus/selected 等状态，配合 Tailwind 的 `data-*` 修饰符即可写条件样式
- **React 与 Vue 双栈**：同一套交互模型分别发布 `@headlessui/react` 与 `@headlessui/vue`，便于跨框架团队复用设计模式
- **与 Tailwind 生态协同**：官方提供 `@headlessui/tailwindcss` 插件；文档示例默认以 Tailwind class 演示，和 Tailwind CSS 工作流天然衔接

## 对用户价值

自建 Dropdown、Modal、Combobox 等交互组件时，焦点顺序、屏幕阅读器语义与键盘行为往往占大量调试时间。Headless UI 把这些易错细节封装在组件内部，你只需关心 markup 结构与视觉样式，原型到生产的交互一致性更高。相比直接套用带皮肤的全量 UI 库，headless 方案在品牌定制与 design token 统一上更灵活；相比从零手写，可显著缩短 a11y 合规与跨浏览器行为对齐的周期。若项目已采用 Tailwind CSS，Headless UI 是同一团队出品、文档与示例风格一致的互补选择。

## 与替代方案

- 相比 [Radix UI](https://www.radix-ui.com/)，Headless UI 同样是无样式、重 a11y 的 primitives，但 API 与 Tailwind 文档示例更紧密；Radix 组件覆盖面更广（含 Accordion、Scroll Area 等），生态与 shadcn/ui 结合更常见，可按组件清单与框架偏好选型。
- 相比 [React Aria / React Spectrum](https://react-spectrum.adobe.com/react-aria/)（Adobe），Headless UI 更轻量、上手路径更短，适合 Tailwind 栈；React Aria 在国际化、复杂表单与大型设计系统场景下能力更完整。
- 相比 [Material UI](https://mui.com/)、[Ant Design](https://ant.design/) 等带主题的全量组件库，Headless UI 不提供现成视觉，但避免被 Material/企业风样式绑定，适合需要独特品牌界面、又不愿重复造交互轮子的团队。
- 边界说明：Headless UI **不是** CSS 框架，也不替代 Tailwind CSS；样式需自行编写。仅支持 React 与 Vue，无 Svelte/Angular 官方包。

## 适应人群

- 使用 React 或 Vue + Tailwind CSS，需要 Dialog、Menu、Listbox 等复杂交互且重视无障碍的前端工程师。
- 在 Radix UI、React Aria 与 Tailwind 系 headless 组件之间做技术选型的团队负责人。
- 已有设计系统或 Figma 规范，希望交互层与视觉层解耦、由工程侧完全掌控样式的 UI 开发者。

## 如何使用

### 前置条件

- Node.js 18+（以项目脚手架与 [headlessui.com](https://headlessui.com) 文档要求为准）。
- 已有 React 或 Vue 应用；若需按文档示例写样式，建议同时安装并配置 [Tailwind CSS](https://tailwindcss.com)。
- npm、pnpm 或 Yarn 等包管理器。

### 安装方式

**React**

```bash
npm install @headlessui/react@latest
```

**Vue**

```bash
npm install @headlessui/vue@latest
```

可选：配合 Tailwind 使用 `@headlessui/tailwindcss` 插件（见 [官方文档](https://headlessui.com) 中 Tailwind 集成说明）。

开发版（跟踪 `main` 分支，**不遵循 semver**）：

```bash
npm install @headlessui/react@insiders
# 或
npm install @headlessui/vue@insiders
```

### 首次运行

以 Dropdown Menu 为例（React）：

```jsx
import { Menu, MenuButton, MenuItem, MenuItems } from '@headlessui/react'

function Example() {
  return (
    <Menu>
      <MenuButton>My account</MenuButton>
      <MenuItems anchor="bottom">
        <MenuItem>
          <a className="block data-focus:bg-blue-100" href="/settings">
            Settings
          </a>
        </MenuItem>
      </MenuItems>
    </Menu>
  )
}
```

Dialog、Tabs、Combobox 等组件的完整 API 与 Vue 写法见 [headlessui.com/react](https://headlessui.com/react/menu) 与 [headlessui.com/vue](https://headlessui.com/vue/menu)。

### 验证是否成功

- 开发服务器启动后，Menu 点击应展开/收起，键盘 Tab 与方向键可导航菜单项。
- 打开 Dialog 时焦点应 trapped 在面板内，按 Esc 或点击遮罩应触发 `onClose`。
- 浏览器 DevTools 中检查触发器与面板节点是否带有合理的 `aria-expanded`、`role` 等属性。

### 常见坑 / 注意事项

- **源码仓库 vs npm 包**：日常项目在依赖中安装 `@headlessui/react` 或 `@headlessui/vue` 即可；clone 本 monorepo 用于贡献或调试 insiders 构建，见 [Contributing](https://github.com/tailwindlabs/headlessui/blob/main/.github/CONTRIBUTING.md)。
- **无内置样式**：组件默认几乎不可见，必须为 `MenuItem`、`DialogPanel` 等节点添加 class 或 CSS；文档依赖 Tailwind 的 `data-focus:`、`data-open:` 等修饰符。
- **受控 vs 非受控**：Dialog 等需显式传入 `open` 与 `onClose`；未正确处理会导致 Esc 或点击外部无法关闭。
- **insiders 版本**：`@insiders` 标签指向 `main` 最新提交，API 可能在正式发布前变动，生产环境请使用 `@latest` 稳定版。
- **与 Tailwind 版本**：Tailwind CSS v4 的 `@import "tailwindcss"` 与 v3 配置路径不同，集成 Headless UI 时请对照各自官方文档，避免 content 扫描或插件注册遗漏。

---

# MongoDB

> 面向文档模型的开源分布式数据库，以 BSON 存储灵活 schema，支持副本集与分片水平扩展。

- 页面：https://www.niceshare.site/github/mongo/
- 仓库：https://github.com/mongodb/mongo
- 官网：https://www.mongodb.com/
- 语言：C++
- Stars：28378
- 许可证：SSPL-1.0
- 标签：开发工具、系统工具、自托管
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

MongoDB 是全球使用最广泛的文档型 NoSQL 数据库之一，本仓库为官方服务端源码，核心组件包括 `mongod`（数据库进程）与 `mongos`（分片路由）。数据以 BSON 文档形式存储，适合 schema 频繁演进、嵌套结构与半结构化负载。生产环境通常优先使用 [MongoDB Community 下载页](https://www.mongodb.com/try/download/community) 或 Docker 镜像，而非直接编译 GitHub 源码；需要向内核贡献代码时，请遵循 [Bug 报告与开发论坛](https://github.com/mongodb/mongo/wiki/Submit-Bug-Reports) 流程。

## 核心特性

- **文档模型与灵活 schema**：JSON/BSON 文档存储，字段可随业务演进，无需预先定义 rigid 表结构
- **副本集与高可用**：自动故障转移、读写分离与跨节点数据冗余
- **分片水平扩展**：`mongos` 路由 + 分片集群，应对海量数据与写入吞吐
- **丰富查询与索引**：单文档、聚合管道、地理空间、全文检索及多类型索引
- **多语言驱动生态**：官方与社区驱动覆盖主流语言，与 Atlas、Compass、mongosh 工具链配套

## 对用户价值

MongoDB 把「像存 JSON 一样存数据」的开发体验与分布式数据库能力结合，缩短从原型到生产的迭代周期。对需要快速上线、嵌套对象多、读多写多且 schema 不固定的应用（内容平台、IoT、用户画像、Catalog 等），文档模型往往比强关系 schema 更顺手。社区版可自托管，也可无缝迁移至 [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) 托管；驱动、University 与文档体系成熟，团队上手成本相对可控。

## 与替代方案

- 相比 **PostgreSQL（JSONB）**，MongoDB 原生文档模型与分片扩展路径更直观；PostgreSQL 在复杂关联查询、ACID 跨表事务与 SQL 生态上通常更强。
- 相比 **Redis**，MongoDB 面向持久化与复杂查询，Redis 更适合内存缓存、队列与极低延迟数据结构。
- 相比 **Couchbase / DynamoDB 等文档或键值云数据库**，MongoDB 自托管与 Atlas 托管并存，API 与工具链统一；纯 AWS 原生栈且强依赖 DynamoDB 专有特性时，DynamoDB 集成更无缝。
- 相比 **MySQL 等传统 RDBMS**，MongoDB 弱化表连接与固定 schema，适合文档中心型应用；强关系约束、报表 JOIN 密集场景关系库仍更合适。

## 适应人群

- 需要文档型存储、快速迭代数据模型的后端开发者与全栈工程师。
- 负责副本集、分片、备份升级与性能调优的 DBA 与运维工程师。
- 评估 NoSQL 架构、许可合规（SSPL）与云迁移成本的技术负责人与数据平台团队。

## 如何使用

### 前置条件

- 日常开发与生产优先通过 [Community 下载页](https://www.mongodb.com/try/download/community)、包管理器或 Docker 安装预编译包，源码构建见 [Building MongoDB](https://github.com/mongodb/mongo/blob/master/docs/building.md)。
- 从源码构建需满足官方文档中的编译器、Python、scons 等依赖；macOS、Linux 均受支持。
- 使用 Community Server 前请阅读 [SSPL 许可说明](https://github.com/mongodb/mongo/blob/master/LICENSE-Community.txt)；2018 年 10 月 16 日前版本为 AGPL，之后版本（含补丁）为 SSPL v1。

### 安装方式

**macOS（Homebrew，推荐日常开发）**

```bash
brew tap mongodb/brew
brew install mongodb-community
brew services start mongodb-community
brew install mongosh
```

**Docker**

```bash
docker pull mongodb/mongodb-community-server
docker run -d --name mongo -p 27017:27017 mongodb/mongodb-community-server
```

**安装 Shell（mongosh）**

```bash
# 或从 https://www.mongodb.com/try/download/shell 下载
brew install mongosh
```

**从本仓库源码构建（开发/定制编译）**

```bash
git clone https://github.com/mongodb/mongo.git
cd mongo
# 详见 docs/building.md
python3 buildscripts/scons.py install-mongod
```

### 首次运行

**单节点本地实例（源码 `./mongod` 或已安装二进制）**

```bash
sudo mkdir -p /data/db
mongod
# 另开终端
mongosh
```

**验证 Shell 连接**

```javascript
// mongosh
help
db.runCommand({ ping: 1 })
```

可选：使用仓库内脚本安装图形化管理工具 Compass：

```bash
./install_compass
```

### 验证是否成功

- `mongod` 进程监听默认端口 27017，日志无 fatal 错误。
- `mongosh` 可连接并执行 `db.runCommand({ ping: 1 })` 返回 `{ ok: 1 }`。
- 插入测试文档后 `db.collection.find()` 可读回数据。

### 常见坑 / 注意事项

- **数据目录权限**：默认 `/data/db` 需可写；Docker 或自定义 `--dbpath` 时注意挂载卷权限。
- **许可与商业使用**：SSPL 对「以 MongoDB 为核心提供 DBaaS」有额外限制，SaaS 或云托管选型前务必做法务评估；AGPL/SSPL 边界以各文件头声明为准。
- **生产高可用**：单节点仅适合开发；生产应配置副本集、备份策略与监控，分片集群需额外部署 `mongos` 与 config server。
- **版本升级**：跨大版本升级前阅读 [Release Notes](https://www.mongodb.com/docs/manual/release-notes/)，关注索引、驱动与 wire protocol 变更。
- **驱动版本**：应用侧驱动 major 版本需与服务端兼容，见 [Drivers 文档](https://www.mongodb.com/docs/manual/applications/drivers/)。

---

# Karakeep

> 可自托管的「万物收藏」应用：链接、笔记与图片入库，AI 自动打标签并支持全文检索。

- 页面：https://www.niceshare.site/github/karakeep/
- 仓库：https://github.com/karakeep-app/karakeep
- 官网：https://karakeep.app
- 语言：TypeScript
- Stars：27189
- 许可证：AGPL-3.0
- 标签：自托管、知识管理、本地模型
- 收录：2026-07-08（更新于 2026-07-08）

## 项目介绍

Karakeep（原名 Hoarder）是一款面向「数据囤积者」的开源自托管收藏应用：链接、短笔记、图片与 PDF 都能丢进去。它会自动抓取标题与预览，用 LLM（含 Ollama 本地模型）做自动打标与摘要，再用 Meilisearch 做全文检索。相对纯书签管理器，它更像自建的稍后读 + 私人档案库，也适合给 Agent 通过 CLI / Skills 来读写。

## 核心特性

- **万物收藏** — 链接、笔记、图片、PDF 统一入库；自动抓取标题、描述与预览图
- **AI 整理** — LLM 自动打标与摘要；支持 OpenAI 等云端模型，也可用 Ollama 做本地推理
- **全文检索与归档** — Meilisearch 搜全文；monolith 整页归档防失效，yt-dlp 可归档视频
- **多端入口** — Chrome / Firefox / Safari 扩展，以及 iOS、Android App，还可从 RSS 自动吸入
- **可扩展集成** — REST API、官方 CLI 与 Agent Skills；支持列表协作、规则引擎、OCR、SSO 与浏览器书签同步（floccus）

## 对用户价值

网上随手看到的文章、工具和视频，往往散落在浏览器书签、聊天记录和临时笔记里，既难找又易失效。Karakeep 把「一键收藏 → AI 归类 → 全文检索 → 整页归档」做成自托管闭环，数据留在自己的服务器上。Pocket 关停之后，它是一条可私有部署、可对接本地模型与 Agent 的稍后读替代路径；不想维护基础设施时，也可使用官方 Cloud。

## 与替代方案

- 相比 **Memos**：Memos 擅长碎片笔记时间线，但不强调链接预览、整页归档与 AI 打标；Karakeep 更适合「收藏互联网内容并可持续找回」。
- 相比 **Linkwarden / Wallabag / Shiori**：它们更偏传统书签或稍后读；Karakeep 额外内建 LLM 打标、OCR、规则引擎，以及面向 Agent 的 CLI / Skills。
- 相比 **Raindrop / mymind**：交互更成熟，但主打商业/非自托管；Karakeep 以 self-hosting first 为定位（另有可选 Cloud）。
- 边界：项目仍处快速迭代；若只要极轻闪念笔记、不需要链接归档与 AI，Memos 往往更省心。

## 适应人群

- Homelab / NAS / VPS 用户，希望自建私有稍后读与书签归档库。
- 想从 Pocket、Chrome、Omnivore 等导入历史书签，并用扩展/App 持续收藏的人。
- 需要用 Ollama 本地打标，或让 Agent（如 OpenClaw）通过 CLI / Skills 操作收藏内容的开发者。

## 如何使用

### 前置条件

- 已安装 Docker 与 Docker Compose。
- 默认可访问主机的 `3000` 端口；准备持久化目录存放 compose 与数据卷。
- 自动打标可选：OpenAI API Key，或按文档配置 Ollama 等其他推理后端。
- 许可证为 AGPL-3.0；生产环境请改强随机密钥，并限制公网暴露（见[安全说明](https://docs.karakeep.app/security-considerations)）。

### 安装方式

官方推荐 Docker Compose（[部署文档](https://docs.karakeep.app/Installation/docker)）：

```bash
mkdir karakeep-app && cd karakeep-app
wget https://raw.githubusercontent.com/karakeep-app/karakeep/main/docker/docker-compose.yml
```

创建 `.env`（密钥请自行替换）：

```bash
KARAKEEP_VERSION=release
NEXTAUTH_SECRET=$(openssl rand -base64 36)
MEILI_MASTER_KEY=$(openssl rand -base64 36)
NEXTAUTH_URL=http://localhost:3000
# 可选：启用云端自动打标
# OPENAI_API_KEY=sk-...
```

```bash
docker compose up -d
```

不想自托管可试用 [Demo](https://try.karakeep.app)（`demo@karakeep.app` / `demodemo`，只读）或 [Karakeep Cloud](https://cloud.karakeep.app)。

### 首次运行

浏览器打开 `http://localhost:3000`，完成注册/登录。建议先收藏一条链接，确认预览抓取正常；若配置了 OpenAI 或 Ollama，检查是否出现自动标签。可选安装[浏览器扩展或移动端 App](https://docs.karakeep.app/)，并把 `NEXTAUTH_URL` 改成实际访问地址。

### 验证是否成功

- Web UI 可登录，新收藏会出现在首页列表，并带有标题/预览。
- 搜索框能命中已保存内容的正文或标签。
- 重启 `docker compose` 后历史数据仍在；可选调用 REST API / CLI 做一次写入验证。

### 常见坑 / 注意事项

- 修改 `.env` 后需重新执行 `docker compose up` 才会生效。
- `KARAKEEP_VERSION=release` 升级时用 `docker compose up --pull always -d`；建议生产环境锁定具体版本。
- AI 打标依赖外部或本地推理；未配置时核心收藏仍可用，但自动标签不会出现。
- 项目迭代快，升级前阅读 Releases；Meilisearch 大版本迁移需单独对照官方排障文档。
- 曾用名 **Hoarder**，检索旧资料时可用该名称；移动端商店包名可能仍带 `hoarder` 字样。

---

# SwitchHosts

> 跨平台 hosts 管理桌面应用，快速切换本地、远程与组合 hosts 方案。

- 页面：https://www.niceshare.site/github/switchhosts/
- 仓库：https://github.com/oldj/SwitchHosts
- 官网：https://switchhosts.vercel.app
- 语言：TypeScript
- Stars：27000
- 许可证：Apache-2.0
- 标签：开发工具、桌面应用、网络工具
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

[SwitchHosts](https://switchhosts.vercel.app) 是一款基于 Tauri 2、React 与 Mantine 的跨平台桌面应用，专门用来管理并切换系统 `hosts` 文件。它把「本地方案、远程订阅、组合规则与文件夹分组」收进同一界面，支持主窗口或系统托盘一键切换，适合需要在开发、测试、内网穿透或临时域名解析之间频繁改 hosts 的用户。项目 Apache-2.0 开源，macOS / Linux / Windows 均可使用，社区 Star 约 2.7 万。

## 核心特性

- **多类型 hosts 条目**：管理系统、本地、远程、组合（Group）与文件夹层级，按需启用不同方案
- **快速切换**：主界面或系统托盘即时切换当前生效的 hosts 组合
- **编辑体验**：hosts 语法高亮，跨条目查找与替换
- **远程 hosts**：支持手动刷新、定时刷新或启动时自动拉取远程内容
- **导入导出**：导出 hosts 数据备份 JSON，也可从 URL 导入备份；条目可移入回收站后恢复或彻底删除
- **偏好与扩展**：写入模式、代理、更新检查、开机启动、应用后执行命令，以及本地 HTTP API

## 对用户价值

手动改 `/etc/hosts`（或 Windows 等价路径）容易出错、难回滚，多套环境并存时更要反复注释与复制粘贴。SwitchHosts 把「编辑 → 预览 → 切换 → 备份」流程可视化：远程 hosts 可定时同步，组合条目让「基础屏蔽 + 项目专用域名」一次启用；应用后命令可配合刷新 DNS 或重启依赖服务。对个人开发者，它降低联调与 A/B 域名解析的摩擦；对团队，导出 JSON 便于共享测试 hosts 片段。数据默认落在 `~/.SwitchHosts`，完整备份只需复制该目录。

## 与替代方案

- 相比**直接编辑系统 hosts 文件**，SwitchHosts 提供语法高亮、回收站、远程订阅与一键切换，减少误删系统行或忘记恢复的风险。
- 相比 **[Gas Mask](https://github.com/2ndalpha/gasmask)**（macOS）等**单平台 hosts 工具**，SwitchHosts 基于 Tauri 覆盖 Win / macOS / Linux，并支持远程 hosts 与 HTTP API。
- 相比 **dnsmasq、/etc/resolver** 等**本地 DNS 方案**，SwitchHosts 只改 hosts 层，部署更轻、适合临时域名或少数条目；若需复杂分流或 DoH，应使用专业 DNS/代理工具（如 Clash、sing-box），二者可并存但职责不同。
- 相比 **HostsMan、SwitchHosts 旧版 Electron 分支**，当前 v5 基于 Tauri 2，数据结构与 README 所述 `manifest.json` + `entries/` 布局更清晰；从旧版迁移需关注备份格式差异（建议先完整复制 `~/.SwitchHosts`）。

## 适应人群

- 需要在开发、预发、生产或内网 hosts 方案间频繁切换的前端与后端开发者。
- 维护远程 hosts 订阅、定时同步测试域名列表的 QA 或运维人员。
- 希望用图形界面管理多条 hosts、避免手改系统文件出错的 macOS / Windows / Linux 桌面用户。

## 如何使用

### 前置条件

- **macOS / Linux / Windows** 任一受支持桌面系统
- 修改 hosts 通常需要**管理员 / root 权限**；首次应用方案时按系统提示授权
- 若从源码构建：需 [Node.js](https://nodejs.org/)、[Rust](https://www.rust-lang.org/tools/install) 及 [Tauri 2 系统依赖](https://v2.tauri.app/start/prerequisites/)

### 安装方式

**预构建版本（推荐）**

从 [GitHub Releases](https://github.com/oldj/SwitchHosts/releases) 或[项目主页](https://switchhosts.vercel.app) 下载对应平台安装包。

**Windows（Chocolatey）**

```powershell
choco install switchhosts
```

**从源码构建**

```bash
git clone https://github.com/oldj/SwitchHosts.git
cd SwitchHosts
npm install
npm run tauri:build
```

打包产物位于 `./src-tauri/target/release/bundle/`。

### 首次运行

1. 安装并启动 SwitchHosts。
2. 在界面中新建**本地**或**远程** hosts 条目，或导入已有备份 JSON / URL。
3. 将需要启用的条目加入**组合（Group）**，在主窗口或托盘选择要应用的方案。
4. 在偏好设置中确认**写入模式**、是否**开机启动**、**应用后命令**（如刷新 DNS）等选项。
5. 首次写入系统 hosts 时授予管理员权限。

### 验证是否成功

- 主界面或托盘显示当前已启用的 hosts 方案名称。
- 打开系统 hosts 文件，确认内容与所选方案一致（路径因系统而异，如 macOS `/etc/hosts`）。
- 对测试域名执行 `ping` 或 `curl`，验证解析是否指向预期 IP。
- 检查数据目录 `~/.SwitchHosts/manifest.json` 与 `entries/` 是否已生成（表示本地数据正常落盘）。

### 常见坑 / 注意事项

- **权限不足**：未授权管理员/root 时无法写入系统 hosts；macOS 需在「系统设置 → 隐私与安全性」中允许。
- **远程 hosts 未更新**：确认网络、代理设置与定时刷新策略；可手动触发刷新排查。
- **备份范围**：应用内导出的 JSON **仅含 hosts 数据**，不含偏好与历史；完整备份请复制整个 `~/.SwitchHosts` 目录。
- **与 VPN / 代理 / 本地 DNS 冲突**：多工具同时改解析时，以最后生效的层为准；联调前建议只启用一套方案。
- **升级 v5**：数据结构相对旧版有变化，升级前建议先备份 `~/.SwitchHosts`，再对照 [Releases](https://github.com/oldj/SwitchHosts/releases) 说明迁移。

---

# GSAP

> 跨框架 JavaScript 动画库，高性能驱动 CSS/SVG/DOM，ScrollTrigger 滚动动效业界标杆。

- 页面：https://www.niceshare.site/github/gsap/
- 仓库：https://github.com/greensock/GSAP
- 官网：https://gsap.com
- 语言：JavaScript
- Stars：26045
- 许可证：Standard License
- 标签：前端、开发工具、可视化
- 收录：2026-06-24（更新于 2026-06-24）

## 项目介绍

GSAP（GreenSock Animation Platform）是业界广泛采用的 JavaScript 动画库，框架无关、零依赖，可驱动 CSS 属性、SVG、Canvas、DOM 属性乃至任意 JavaScript 对象。官方宣称在超过 1200 万个站点上验证过稳定性，并主动处理大量浏览器兼容差异。2024 年起在 Webflow 支持下，**包括 ScrollTrigger、SplitText、MorphSVG 等全部插件均已免费**，商业项目亦可使用（详见 [Standard License](https://gsap.com/standard-license)）。

## 核心特性

- **高性能属性插值**：以精确的时间轴更新属性值，官方称较 jQuery 动画最高可达约 20 倍速度
- **丰富插件生态**：ScrollTrigger（滚动驱动）、MotionPathPlugin（路径动画）、Flip（布局过渡）、Draggable、SplitText、MorphSVG 等可按需注册
- **响应式与无障碍**：`gsap.matchMedia()` 便于按断点切换动画，支持构建可访问的动效方案
- **框架无关集成**：原生 JS、React（`@gsap/react` 的 `useGSAP`）、Vue、WebGL 等场景均可使用
- **完善学习资源**：[gsap.com/docs](https://gsap.com/docs/)、[Demos](https://gsap.com/demos)、[Ease Visualizer](https://gsap.com/docs/v3/Eases) 与活跃社区论坛

## 对用户价值

手写 CSS `@keyframes` 或 `requestAnimationFrame` 难以处理复杂序列、暂停/恢复、时间轴编排与跨浏览器一致性。GSAP 提供 `timeline`、`to`/`from`/`fromTo` 等统一 API，让落地页滚动叙事、产品微交互、数据可视化过渡等场景能以少量代码实现电影级编排。ScrollTrigger 已成为滚动动效的事实标准；与 Anime.js 等轻量库相比，GSAP 在复杂序列控制、插件深度与生产稳定性上更具优势，适合对动效品质有要求的商业项目。

## 与替代方案

- 相比 [Anime.js](https://github.com/juliangarnier/anime)，GSAP API 更重时间轴与插件体系，学习曲线略陡，但复杂编排、滚动联动与 FLIP 布局动画等高级场景工具更完整；Anime.js 更轻量，适合简单属性动画。
- 相比 [Framer Motion](https://www.framer.com/motion/)（React 生态），GSAP 框架无关、可在任意技术栈复用，ScrollTrigger 等滚动能力更成熟；Framer Motion 与 React 声明式组件模型结合更紧密，适合纯 React 项目的布局/手势动画。
- 相比纯 CSS 动画，GSAP 提供运行时控制（暂停、反向、seek、stagger）、动态目标与 JS 对象插值，但会增加 JS 包体积；简单 hover/过渡可优先 CSS，复杂叙事再引入 GSAP。
- 边界说明：部分历史文档仍提及 Club GSAP 付费插件；自 2024 年 4 月起全套工具已免费，集成前请以 [gsap.com/install](https://gsap.com/install) 与 Standard License 为准。

## 适应人群

- 需要为落地页、营销站点或产品界面实现滚动叙事、品牌动效的前端工程师与创意开发者。
- 在 React/Vue 项目中评估动画方案，希望统一时间轴 API 并接入 ScrollTrigger 的团队。
- 从 jQuery 动画或 CSS keyframes 迁移，追求更精细的序列控制与跨浏览器一致性的维护者。

## 如何使用

### 前置条件

- 现代浏览器（支持 ES modules 的环境；CDN 方案仅需 HTML）。
- Node.js 与 npm/pnpm/Yarn（npm 集成时）。
- 基础 JavaScript；了解 CSS 属性或 DOM 结构有助于编写 `gsap.to()` 目标。

### 安装方式

**方式一：npm（推荐，打包项目）**

```bash
npm install gsap
```

```javascript
import gsap from "gsap";
import ScrollTrigger from "gsap/ScrollTrigger";

gsap.registerPlugin(ScrollTrigger);
```

也可从 `gsap/all` 一次性导入多个插件（不含 members-only 插件）：

```javascript
import { gsap, ScrollTrigger, Draggable, Flip, MotionPathPlugin } from "gsap/all";

gsap.registerPlugin(ScrollTrigger, Draggable, Flip, MotionPathPlugin);
```

**方式二：CDN（快速原型）**

```html
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15/dist/gsap.min.js"></script>
```

更多 CDN 与插件链接见 [JSDelivr GSAP 专页](https://www.jsdelivr.com/gsap) 与 [安装指南](https://gsap.com/install)。

**方式三：React 项目**

```bash
npm install gsap @gsap/react
```

参阅 [React 指南](https://gsap.com/react) 使用 `useGSAP()` 钩子替代 `useEffect`，自动处理清理逻辑。

### 首次运行

最小示例：将元素在 1 秒内移动到 `x: 200`：

```javascript
import gsap from "gsap";

gsap.to(".box", { x: 200, duration: 1 });
```

HTML 中需有对应元素，例如 `<div class="box"></div>`。更完整的入门路径见 [Getting Started](https://gsap.com/get-started/) 与 [Cheat Sheet](https://gsap.com/cheatsheet)。

### 验证是否成功

- 页面加载后目标元素应平滑移动，浏览器控制台无模块解析或 `registerPlugin` 相关报错。
- 使用 ScrollTrigger 时，滚动页面应触发预期动画；未注册插件时相关 API 会不可用。
- 打包项目执行 `npm run dev` / `npm run build` 应无 `gsap` 路径错误。

### 常见坑 / 注意事项

- **插件必须注册**：`ScrollTrigger`、`Flip` 等需 `gsap.registerPlugin(...)` 后方能使用，仅 `import gsap` 不够。
- **许可证变更**：2024 年前部分插件需 Club 会员；当前全套免费，但许可为 GreenSock Standard License 而非 MIT，商业使用前请阅读 [standard-license](https://gsap.com/standard-license)。
- **React 清理**：在 React 中优先使用 `@gsap/react` 的 `useGSAP`，避免在 `useEffect` 中遗漏 `kill()` 导致内存泄漏或动画叠加。
- **包体积**：按需 import 单个插件，避免无谓引入 `gsap/all` 中的全部工具。
- **版本升级**：关注 [Releases](https://github.com/greensock/GSAP/releases) 与 [文档 v3](https://gsap.com/docs/v3/)，GSAP 3.x 与 2.x API 差异较大，迁移需对照官方说明。

---

# claude-hud

> Claude Code 状态栏插件，实时展示上下文用量、工具调用、子代理与待办进度。

- 页面：https://www.niceshare.site/github/claude-hud/
- 仓库：https://github.com/jarrodwatts/claude-hud
- 语言：JavaScript
- Stars：25647
- 许可证：MIT
- 标签：AI 编程、Agent、开发工具
- 收录：2026-06-24（更新于 2026-06-24）

## 项目介绍

claude-hud 是 Jarrod Watts 为 Claude Code 开发的**终端状态栏（statusline）插件**，利用官方 statusline API 在输入框下方常驻显示会话信息。它读取 Claude Code 原生的 token 与用量数据（非估算），并解析 transcript JSONL 以追踪工具调用、子代理运行与 Todo 进度，约每 300ms 刷新，无需额外窗口或 tmux 分屏。

## 核心特性

- **上下文健康度**：彩色进度条（绿→黄→红）显示上下文窗口占用，支持 1M context 等新窗口尺寸
- **用量与限流**：展示 Claude 订阅用量、重置倒计时与可选 7 日用量阈值提醒
- **工具与代理追踪**：实时显示 Read/Edit/Grep 等工具活动，以及子代理名称、模型与运行时长
- **Todo 进度**：同步 Claude Code 内置待办列表的完成状态（如 `2/5`）
- **Git 与项目路径**：可配置 1–3 级目录深度、分支名、脏状态与 ahead/behind 提示
- **可定制布局**：`/claude-hud:configure` 引导配置 Full / Essential / Minimal 预设，支持中英文标签与紧凑/展开布局

## 对用户价值

长时间 Agent 会话里，上下文悄悄填满、子代理在后台跑、Todo 进度不可见——这些问题往往要到报错或手动 `/context` 才被发现。claude-hud 把关键指标压进终端底部一行或数行，让你在继续输入前就能判断是否需要压缩上下文、暂停任务或检查代理状态，减少「突然撞墙」的中断成本。

## 与替代方案

- 相比手动执行 `/context` 或翻阅 transcript，本插件提供**持续、低打扰**的可视化，且数据来自 Claude Code 原生 API，比第三方估算更可靠。
- 相比自建 tmux 分屏或外部监控脚本，claude-hud 直接接入 statusline 管道（stdin JSON → 渲染 → stdout），与 Claude Code 终端体验一体，无需额外窗口管理。
- 相比 [claude-mem](https://github.com/thedotmack/claude-mem) 等侧重跨会话记忆的插件，claude-hud 专注**当前会话的可观测性**，二者可并存；若你只需要 HUD 而不需要持久记忆，单独安装本插件即可。
- 局限：仅适用于 Claude Code 且需完成 statusline 配置；非 Claude Code 用户或不需要终端 HUD 的场景不适用。

## 适应人群

- 每天用 Claude Code 在同一代码库上长时间结对编程的开发者。
- 频繁启用子代理、Skills 或 MCP，需要一眼看清「后台在干什么」的效率型用户。
- 关心上下文余量与订阅用量，希望在撞限前主动调整会话策略的 Claude 订阅用户。

## 如何使用

### 前置条件

- 已安装并登录 **Claude Code**
- **Linux**：若插件安装报 `EXDEV: cross-device link not permitted`，需将 `TMPDIR` 指向非 tmpfs 目录（见下方安装说明）
- **Windows**：运行 `/claude-hud:setup` 前需有 Node.js LTS（可用 `winget install OpenJS.NodeJS.LTS`）

### 安装方式

在 Claude Code 会话内执行：

```text
/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/reload-plugins
```

**Linux 用户**（遇跨设备链接错误时）：

```bash
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
```

在上述会话中再执行安装命令。

配置 statusline（必需）：

```text
/claude-hud:setup
```

完成后**完全重启** Claude Code 以加载新的 `statusLine` 配置。

### 首次运行

重启后，输入框下方应出现默认两行 HUD：第一行显示模型、项目路径与 git 分支；第二行显示上下文条与用量条。可选运行 `/claude-hud:configure` 选择预设、切换中文标签（`zh` / `zh-Hans`）或开启工具/代理/Todo 附加行。

### 验证是否成功

- 终端底部出现带彩色 `████░░░░` 上下文条的 statusline
- `/claude-hud:configure` 可打开引导式配置且预览生效
- 触发文件读写或子代理时，若已启用对应选项，附加行应随活动更新

### 常见坑 / 注意事项

- 安装后 HUD 不显示：确认已执行 `/claude-hud:setup` 并**完整重启** Claude Code，而非仅 reload 插件。
- Linux `/tmp` 在 tmpfs 上会导致插件安装失败，按 README 设置 `TMPDIR=~/.cache/tmp` 后再装。
- Windows 若 setup 提示找不到 JavaScript 运行时，安装 Node.js LTS 后重启 shell 再跑 setup。
- 高级选项（颜色、阈值、`pathLevels` 等）可编辑 `~/.claude/plugins/claude-hud/config.json`；运行 configure 会保留这些手动设置。

---

# Codex Plugin for Claude Code

> OpenAI 官方 Claude Code 插件，在终端内直接调用 Codex 做代码审查与任务委派。

- 页面：https://www.niceshare.site/github/codex-plugin-cc/
- 仓库：https://github.com/openai/codex-plugin-cc
- 语言：JavaScript
- Stars：23018
- 许可证：Apache-2.0
- 标签：AI 编程、Agent、开发工具
- 收录：2026-07-03（更新于 2026-07-03）

## 项目介绍

这是 OpenAI 为 **Claude Code** 推出的官方 Codex 插件，让你在熟悉的 Claude Code 工作流里直接调用本地 Codex CLI：做只读代码审查、对抗式设计质询，或把调试与修复任务委派给 Codex 在后台执行。插件通过 Codex App Server 对接本机已安装的 `codex` 二进制，复用同一套登录态与 `config.toml` 配置，适合不想在 Claude 与 Codex 之间来回切换终端的开发者。

## 核心特性

- **Slash 命令审查**：`/codex:review` 对未提交改动或相对 `main` 等基线的分支做只读审查；支持 `--background` 与 `--wait`
- **对抗式审查**：`/codex:adversarial-review` 可附加聚焦文本，质疑设计取舍、失败模式与替代方案
- **任务委派与救援**：`/codex:rescue` 通过 `codex:codex-rescue` 子 Agent 调查 Bug、尝试修复或续接上次任务，支持 `--model`、`--effort`、`--resume`
- **会话与作业管理**：`/codex:transfer` 将 Claude Code 对话导入 Codex 线程；`/codex:status`、`/codex:result`、`/codex:cancel` 管理后台作业
- **一键环境检测**：`/codex:setup` 检查 Codex 是否就绪，必要时可引导通过 npm 安装

## 对用户价值

Claude Code 擅长交互式结对，Codex 则在审查与长时自主任务上各有优势。本插件把两者串进同一终端会话：审查类工作走只读 Slash 命令，重活可丢给 Codex 后台跑，再用 `codex resume` 在 Codex App 或 TUI 里续写。无需维护两套独立工作区，也无需重复登录——插件直接读取本机 Codex CLI 的鉴权与配置。

## 与替代方案

- 相比 **单独开 Codex CLI**，本插件把审查、委派、状态查询收敛为 Claude Code 内 Slash 命令，并与 Claude 会话上下文联动（如 `/codex:transfer` 导入历史）。
- 相比 **Claude Code 内置 `/review` 或第三方审查插件**，审查质量对齐 Codex 原生 `/review`；对抗式审查与后台作业管理是 Codex 侧能力，需 ChatGPT 订阅或 API Key 并计入 Codex 用量。
- 相比 **Continue、Aider 等多模型工具**，本插件深度绑定 OpenAI Codex 生态，不适合只想切换任意 LLM 的场景。
- 若团队只用 Claude 模型、不打算引入 Codex 账户，Anthropic 官方 [claude-plugins-official](https://github.com/anthropics/claude-plugins-official) 内的 code-review 等插件可能更轻。

## 适应人群

- 已日常使用 Claude Code，同时订阅 ChatGPT 或持有 OpenAI API Key、希望把 Codex 审查与委派纳入同一工作流的开发者。
- 需要在提交前做分支级代码审查，或希望对架构决策做对抗式压力测试的工程师。
- 习惯让 Agent 在后台跑长任务，并希望通过 `codex resume` 在 Codex App 中继续审查结果的团队。

## 如何使用

### 前置条件

- 已安装并可正常启动 [Claude Code](https://github.com/anthropics/claude-code) CLI。
- **ChatGPT 订阅（含 Free）或 OpenAI API Key**；用量计入 [Codex 限额](https://developers.openai.com/codex/pricing)。
- **Node.js 18.18 或更高版本**（用于安装 Codex CLI）。

### 安装方式

在 Claude Code 中添加插件市场并安装：

```bash
/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins
```

然后运行环境检测：

```bash
/codex:setup
```

若需手动安装 Codex CLI：

```bash
npm install -g @openai/codex
```

若 Codex 已安装但未登录：

```bash
!codex login
```

### 首次运行

安装完成后应能看到本文列出的 Slash 命令，以及 `/agents` 中的 `codex:codex-rescue` 子 Agent。建议先做一次后台审查流程：

```bash
/codex:review --background
/codex:status
/codex:result
```

### 验证是否成功

- `/codex:setup` 报告 Codex 就绪，且 `codex` 命令在 PATH 中可用。
- `/codex:review` 能对当前改动或 `--base main` 分支返回审查结果。
- 后台任务可通过 `/codex:status` 查看进度，`/codex:result` 可拿到会话 ID 供 `codex resume` 使用。

### 常见坑 / 注意事项

- 多文件审查可能耗时较长，官方建议优先使用 `--background`，再用 `/codex:status` 轮询。
- `/codex:review` 与 `/codex:adversarial-review` 均为**只读**，不会自动改代码；修复请用 `/codex:rescue`。
- 插件使用本机 Codex CLI 与 App Server，项目级 `.codex/config.toml` 仅在 [项目被信任](https://developers.openai.com/codex/config-advanced#project-config-files-codexconfigtoml) 时生效。
- `/codex:transfer` 要求 Claude 会话文件位于 `~/.claude/projects`，且 Codex 版本需支持外部 Agent 会话导入。
- 自定义 OpenAI 端点可在 Codex 配置中设置 `openai_base_url`，插件会沿用现有鉴权方式。

---

# localtunnel

> 将本机 localhost 暴露为公网 HTTPS URL，无需改 DNS 或部署即可分享与联调。

- 页面：https://www.niceshare.site/github/localtunnel/
- 仓库：https://github.com/localtunnel/localtunnel
- 官网：https://localtunnel.me
- 语言：JavaScript
- Stars：22338
- 许可证：MIT
- 标签：开发工具、CLI、自动化
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

[localtunnel](https://localtunnel.me) 是一款经典的内网穿透客户端：在本地启动后，它会连到公共隧道服务器，把 `localhost` 上的端口映射成一个可分享的 HTTPS 公网地址。适合 Webhook 回调联调、让同事或测试工具访问你本机上的服务，而不用为了演示去改 DNS 或临时部署到云端。项目提供 CLI（`lt`）与 Node.js API，生态里还有 Go、.NET、Rust 等第三方客户端。

## 核心特性

- **一行启动**：`npx localtunnel --port 8000` 或 `lt --port 8000` 即可拿到公网 URL，会话期间地址保持有效
- **自动重连**：本地服务重启后，客户端会检测并自动重新连接隧道
- **自定义子域**：`--subdomain` 可请求固定子域名（视服务器可用性而定）
- **灵活代理目标**：`--local-host` 可把流量转发到非 `localhost` 的主机名；支持本地 HTTPS 与自签证书选项
- **程序化 API**：`localtunnel(port, options)` 返回 Promise，便于测试脚本与 CI 集成
- **多语言客户端**：官方 Node 客户端之外，社区提供 Go、C#/.NET、Rust 等实现

## 对用户价值

本地开发最常卡在外部系统「必须回调公网 URL」：支付网关、Twilio、OAuth、移动端真机调试、Browserling 等浏览器测试工具，都要求一个能从互联网访问的地址。自建反向代理或买 VPS 成本高、流程重；localtunnel 用托管隧道服务器把这件事收成一条命令。对个人开发者，它是快速分享 Demo 与验证 Webhook 的零配置方案；对团队，固定子域与 API 模式也方便写进自动化测试。MIT 许可，可自由嵌入项目或二次封装。

## 与替代方案

- 相比 **[ngrok](https://ngrok.com/)**，localtunnel **完全开源、可自托管服务端**（见 [localtunnel/server](https://github.com/localtunnel/server)），默认公共实例免费且无需注册；ngrok 在稳定性、Inspect 面板与企业功能上更成熟，但免费档有会话与连接限制。
- 相比 **[Cloudflare Tunnel (cloudflared)](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/)**，localtunnel **上手更轻、一条命令即用**，适合临时联调；Cloudflare Tunnel 更适合长期绑定自有域名、走 Zero Trust 的生产流量，但配置与账号依赖更重。
- 相比 **[serveo](https://serveo.net/)** 等 SSH 隧道方案，localtunnel **基于 Node/npm 生态**，对前端与 Node 开发者更顺手；SSH 方案无需安装 Node，但子域与稳定性依赖第三方服务政策。
- 若需要**生产级 SLA、固定自定义域名与访问审计**，应选 ngrok 付费档或 Cloudflare Tunnel；若只需**内网互通**、不需要公网入口，直接用局域网 IP 或 mDNS 更简单。

## 适应人群

- 需要在本地跑服务并让外网（或手机）访问的 Web / 全栈开发者。
- 对接 Twilio、Stripe、GitHub Webhook 等必须公网回调的集成与自动化工程师。
- 希望用 Node API 把隧道写进 E2E 测试或演示脚本的技术写作者。

## 如何使用

### 前置条件

- 本机已安装 **Node.js**（用于 `npx` / `npm`）或 **Homebrew**（macOS 可选安装方式）
- 本地有一个正在监听端口的 HTTP/HTTPS 服务（例如 `8000`、`3000`）
- 网络可访问默认上游服务器 `https://localtunnel.me`（企业环境若被墙或拦截，需改用自托管 [localtunnel/server](https://github.com/localtunnel/server) 并配置 `host` 选项）

### 安装方式

**无需安装（推荐快速试用）**

```bash
npx localtunnel --port 8000
```

**全局安装 CLI**

```bash
npm install -g localtunnel
```

**作为项目依赖**

```bash
yarn add localtunnel
# 或
npm install localtunnel
```

**macOS Homebrew**

```bash
brew install localtunnel
```

### 首次运行

1. 在终端启动你的本地服务，确认端口可访问（例如 `http://localhost:8000`）。
2. 另开终端执行：

```bash
lt --port 8000
```

3. 终端会输出分配的公网 URL（形如 `https://<subdomain>.loca.lt` 或历史文档中的 `localtunnel.me` 域名，以当前客户端输出为准）。
4. 把该 URL 填到 Webhook 配置、手机浏览器或协作方的测试工具中即可访问你本机服务。
5. 可选参数示例：

```bash
lt --port 8000 --subdomain my-demo
lt --port 3000 --local-host 127.0.0.1
PORT=3000 lt
```

**Node.js API 示例**

```js
const localtunnel = require("localtunnel");

(async () => {
  const tunnel = await localtunnel({ port: 3000 });
  console.log(tunnel.url);
  tunnel.on("close", () => {
    // 隧道已关闭
  });
})();
```

### 验证是否成功

- CLI 启动后应打印公网 URL，且无持续报错。
- 在**另一台设备或手机 4G 网络**打开该 URL，应能访问你本地对应端口的页面或 API。
- 若配置了 Webhook，在外部服务后台触发一次事件，本地服务日志应收到回调请求。
- 重启本地服务后，保持 `lt` 进程运行，确认隧道能自动恢复（README 描述的行为）。

### 常见坑 / 注意事项

- **公共实例非生产用途**：默认 `localtunnel.me` 为共享服务，适合开发联调；敏感数据、长期在线或高可用场景请自托管 server 或改用 ngrok / Cloudflare Tunnel。
- **子域不保证可用**：`--subdomain` 请求的名称可能被占用或拒绝，失败时换名或使用随机子域。
- **HTTPS 与证书**：代理本地 HTTPS 时需按 README 配置 `local_https`、`local_cert`、`local_key` 等；自签证书可配合 `allow_invalid_cert`。
- **会话生命周期**：URL 通常在 `lt` 进程存活期间有效，关闭终端或 `tunnel.close()` 后外网地址失效，Webhook 需同步更新。
- **仓库 Issues 较多**：社区反馈连接稳定性、域名变更等问题时，优先查阅 [Issues](https://github.com/localtunnel/localtunnel/issues) 与 server 仓库文档；联调关键路径建议准备备用隧道方案。

---

# Meetily

> 隐私优先的本地 AI 会议助理：实时转录、摘要与录音整理，数据不出本机，支持 macOS/Windows。

- 页面：https://www.niceshare.site/github/meetily/
- 仓库：https://github.com/Zackriya-Solutions/meetily
- 官网：https://meetily.ai
- 语言：Rust
- Stars：21402
- 许可证：MIT
- 标签：本地模型、自托管、知识管理
- 收录：2026-07-08（更新于 2026-07-08）

## 项目介绍

Meetily（Community Edition）是一款隐私优先的桌面 AI 会议助理：在本机捕获音频、实时转写，并可接 Ollama 等模型生成摘要。核心链路基于 Rust / Tauri，转录走 Whisper 或 Parakeet，默认不把会议内容送上公有云，适合把「会议纪要」留在自己设备上的个人与合规敏感团队。

## 核心特性

- 本地优先：录音、转写与摘要默认在本机完成，敏感对话不必托管给第三方会议 AI
- 实时转写：会议进行中即可看到文字流；也可导入已有音频后离线增强/重转写（Beta）
- 多模型摘要：推荐 Ollama（本地），也支持 Claude、Groq、OpenRouter 及自建 OpenAI 兼容端点
- 专业拾音：同时采集麦克风与系统音频，带 ducking 与削波防护，适配 Zoom / Teams 等场景
- GPU 加速：macOS（Metal / CoreML）、Windows/Linux（CUDA / Vulkan）构建时自动启用

## 对用户价值

云端会议助手好用，但合规、客户保密与跨境数据往往过不了关。Meetily 把「录下来 → 转成字 → 写成纪要」收拢到本地或自管推理栈，用开源模型替代按分钟计费的商业 API，离线也能继续转写；对律师、顾问、医疗与企业高管，核心收益是数据主权，而不仅是「又一个笔记工具」。

## 与替代方案

- 相比 Otter / Fireflies / Notion AI Meeting Notes 等云端助手，Meetily 默认本机处理，隐私与合规边界更清晰，但安装、模型下载与本机算力要自己扛。
- 相比纯 Whisper CLI / whisper.cpp 流水线，Meetily 提供桌面拾音、实时字幕与摘要编辑的一体化体验，上手成本更低；自定义流水线则 CLI 更灵活。
- 仓库另有 Meetily PRO / Enterprise（闭源商业产品）提供更高精度转写、导出模板、团队自托管等；社区版承诺继续免费开源，选型时勿把 README 营销功能与 CE 功能混为一谈。
- 许可证为 MIT；若摘要走 Claude/Groq 等云 API，该段文字会离开本机，需按组织策略单独评估。

## 适应人群

- 需要会议纪要、又不允许把录音送进 SaaS 的法务、医疗、咨询与政府/国防相关从业者。
- 已在跑 Ollama / 本地 Whisper，希望把转写与摘要收进桌面 App 的隐私向个人用户。
- 想自托管会议智能能力、愿从 Community Edition 试用再评估 PRO 的小团队。

## 如何使用

### 前置条件

- 操作系统：官方安装包面向 **macOS** 与 **Windows**；Linux 需按文档从源码构建。
- 硬件：本地 Whisper / Parakeet 转写与摘要对 CPU/GPU 与内存有要求；Apple Silicon 或带 CUDA 的 NVIDIA 卡体验更好。
- 可选：若要用本地摘要，先准备好 [Ollama](https://ollama.com) 并拉取常用对话模型；若只用云端摘要，准备好对应 API Key。

### 安装方式

**Windows：** 从 [Releases](https://github.com/Zackriya-Solutions/meeting-minutes/releases/latest) 下载最新 `x64-setup.exe` 并运行安装程序。

**macOS：**

1. 下载 `meetily_*_aarch64.dmg`（以 Release 页实际文件名为准）
2. 打开 `.dmg`，将 Meetily 拖入 Applications
3. 从「应用程序」启动 Meetily

**Linux（从源码构建，快速参考）：**

```bash
git clone https://github.com/Zackriya-Solutions/meeting-minutes
cd meeting-minutes/frontend
pnpm install
./build-gpu.sh
```

完整构建步骤见仓库 [`docs/building_in_linux.md`](https://github.com/Zackriya-Solutions/meetily/blob/main/docs/building_in_linux.md) 与 [`docs/BUILDING.md`](https://github.com/Zackriya-Solutions/meetily/blob/main/docs/BUILDING.md)。注意：Release 资源仍挂在历史仓库名 `meeting-minutes` 下，与当前 `meetily` 仓库指向同一产品线。

### 首次运行

1. 启动 Meetily，在设置中选择系统音频与麦克风设备，确认能同时采集远端与本端声音。
2. 下载/选择转写模型（Whisper 或 Parakeet），按会议语言配置。
3. 配置摘要提供方：优先 Ollama 本机；或填入 Claude / Groq / OpenRouter / 自定义 OpenAI 兼容 Base URL 与 Key。
4. 开一场测试会议或导入一段已有录音，生成转写与摘要并保存。

### 验证是否成功

- 会议进行中转写面板持续出字，无明显长时间卡住。
- 结束后能生成可读摘要，且录音/转写文件落在本机存储路径（可在设置中核对）。
- 仅开本地链路时，抓包或防火墙侧不应出现向未知会议 SaaS 上传音频的流量；若配置了云端 LLM，仅摘要请求应发往你指定的端点。

### 常见坑 / 注意事项

- README 功能列表写「支持 Linux」，但桌面安装包当前以 macOS/Windows 为主；Linux 用户请按构建文档操作，勿假设有现成 AppImage/deb。
- 系统音频采集在 macOS 上常需额外权限或虚拟声卡配置，首次使用务必先做拾音测试。
- GitHub description 提到 speaker diarization；社区版与 PRO 功能边界仍在演进，正式依赖说话人分离前请对照当前 Release 说明，避免按营销文案选型。
- Community Edition 与 PRO 是不同产品线；高级导出、自动入会、团队自托管等能力默认属于 PRO，不要期待全部在开源 CE 中可用。
- 当前 API 返回的 `contributors` 快照偏低，详情页贡献者人数仅作参考，以 GitHub 贡献图为准。

---

# herdr

> 终端里的 Agent 多路复用器：真终端视图、一眼看清状态，分离后 Agent 继续跑。

- 页面：https://www.niceshare.site/github/herdr/
- 仓库：https://github.com/ogulcancelik/herdr
- 官网：https://herdr.dev
- 语言：Rust
- Stars：21278
- 许可证：Apache-2.0
- 标签：Agent、AI 编程、CLI
- 收录：2026-07-27（更新于 2026-07-27）

## 项目介绍

herdr 是一款跑在现有终端里的 **Agent 多路复用器**（agent multiplexer）：用真实终端视图管理 Claude Code、Codex、OpenCode 等编码 Agent，侧栏一眼区分 blocked / working / done，而不是再包一层「解释过的」UI。单 **Rust** 二进制、无 Electron；支持鼠标与 tmux 式前缀键、分离后 Agent 继续跑、SSH 重连，并提供纯 Socket API 让 Agent 彼此编排。

## 核心特性

- **全局面板**：每个 Agent 的 blocked / working / done / idle 状态跨 workspace 可见，真终端输出而非包装视图
- **分离与持久**：`ctrl+b q` 分离或关掉终端窗口后 Agent 仍在跑；任意终端或 SSH 再执行 `herdr` 即可重连
- **键鼠双一流**：tmux 风格前缀键与点击、拖拽分屏、右键菜单并存，按场景选用
- **Agent 可调用 herdr**：纯 Socket API，Agent 可开 pane、读输出、互相等待；配套 [agent skill](https://herdr.dev/docs/agent-skill/)
- **插件与轻量运行时**：插件扩展 pane / 工作流（[marketplace](https://herdr.dev/plugins/)）；一个二进制跑在你已有的终端里

## 对用户价值

同时开多个编码 Agent 时，最痛的是「哪个在等人、哪个在干活、关掉窗口会不会断」。herdr 把多 Agent 收进带状态侧栏的 multiplexer：真终端、可分离重连、会话可跨重启，适合本地与远程 SSH 同一套心智。需要 Agent 自己开 pane、等彼此完成时，Socket API 把编排留在终端运行时内，而不必另搭 Electron 桌面壳。

## 与替代方案

- 相比 **tmux / Zellij** 等通用终端多路复用器，herdr 面向 **编码 Agent**：自动识别 Claude / Codex 等，侧栏展示 Agent 状态，并提供 Agent 可用的 Socket API。
- 相比 [Gas Town](https://github.com/gastownhall/gastown) 等 **多 Agent 任务编排 / 合并队列** 工具，herdr 更偏 **终端会话与 pane 运行时**，不替你做 Bead 账本或 PR 合并流水线；可互补使用。
- 相比 Electron 桌面 Agent IDE，herdr 是 **一个 Rust 二进制 + 现有终端**，更轻、更适合 SSH / 远程；代价是依赖你本机已有的 CLI Agent。
- 若只偶尔开 1 个 Agent，通用 multiplexer 可能够用；若要「多 Agent 一眼可扫 + 分离不丢 + Agent 互调」，herdr 定位更准。

## 适应人群

- 日常并行跑 **Claude Code、Codex、OpenCode、pi** 等终端编码 Agent 的开发者。
- 习惯 tmux，但希望侧栏直接看到 Agent 忙闲、并支持鼠标分屏的用户。
- 需要 SSH / 远程重连、会话与 Agent 在分离后仍存活的进阶终端用户。

## 如何使用

### 前置条件

- 一台可运行安装脚本的环境：**macOS / Linux**（推荐），Windows 为 beta。
- 本机已安装至少一种终端编码 Agent（如 `claude`、`codex`、`opencode`、`pi` 等）；完整列表见 [supported agents](https://herdr.dev/docs/agents/)。
- 任意现代终端模拟器即可；无需 Electron。

### 安装方式

```bash
# 官方一键安装（推荐）
curl -fsSL https://herdr.dev/install.sh | sh
```

其他方式：

```bash
brew install herdr
# 或
mise use -g herdr
```

Windows（beta）：

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
```

亦可从 [Releases](https://github.com/ogulcancelik/herdr/releases) 下载预编译二进制。

### 首次运行

在项目目录启动（会启动或附着到默认后台 session）：

```bash
herdr
```

在 pane 里启动 Agent，例如：

```bash
claude
# 或 codex / opencode / pi 等
```

herdr 会自动识别；侧栏显示 working / blocked / done / idle。常用：`ctrl+b` 进入前缀模式，`prefix+v` 右分屏，`prefix+c` 新标签，`prefix+q` 分离。完整绑定见 [keyboard](https://herdr.dev/docs/keyboard/)，站内可按 `prefix+?`。

### 验证是否成功

- 运行 `herdr` 后出现 workspace / pane UI，侧栏能看到 Agent 状态变化。
- `prefix+q` 分离后关掉终端，再执行 `herdr` 应重连到同一 session，Agent 仍在运行。
- 在 pane 中启动支持的 Agent，确认被自动识别且状态不是长期错误的 idle。

要真正结束 session 并停掉 panes：

```bash
herdr server stop
```

### 常见坑 / 注意事项

- **分离 ≠ 停止**：关窗口或 `prefix+q` 后 Agent 仍在跑；要停干净用 `herdr server stop`。
- Windows 安装路径仍为 **beta**，行为可能与 macOS / Linux 有差异。
- 鼠标链接：macOS 上 pane 内链接常用 **Ctrl-click**；Cmd-click 依赖终端原生旁路（如关闭 `ui.mouse_capture`）。详见 [quick start](https://herdr.dev/docs/quick-start/)。
- 配置、远程、`herdr --remote`、插件与 Socket API 以 [herdr.dev/docs](https://herdr.dev/docs/) 为准；升级前查看 Releases 是否有破坏性变更。

---

# PostgreSQL

> 成熟的开源对象关系型数据库，支持 ACID 事务、扩展 SQL 与 JSON/地理空间等高级能力。

- 页面：https://www.niceshare.site/github/postgres/
- 仓库：https://github.com/postgres/postgres
- 官网：https://www.postgresql.org/
- 语言：C
- Stars：21199
- 许可证：PostgreSQL
- 标签：开发工具、系统工具、自托管
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

PostgreSQL 是全球使用最广泛的开源对象关系型数据库管理系统（ORDBMS）之一，由全球开发者社区持续维护三十余年。本 GitHub 仓库为官方 Git 源码镜像，涵盖完整数据库内核与 C 语言绑定；生产环境通常优先使用 [postgresql.org](https://www.postgresql.org/download/) 提供的二进制包，而非直接编译镜像仓库。需要向项目贡献代码时，请遵循 [PostgreSQL 官方补丁提交流程](https://wiki.postgresql.org/wiki/Submitting_a_Patch)，本镜像不接受 Pull Request。

## 核心特性

- **ACID 与 MVCC**：完整事务语义，多版本并发控制减少读写锁争用
- **扩展 SQL 能力**：CTE、窗口函数、外键、子查询、触发器与用户自定义类型/函数
- **半结构化与检索**：原生 JSON/JSONB、全文检索、数组与范围类型
- **可扩展架构**：通过扩展（如 PostGIS、pgvector）按需增强地理空间、向量检索等能力
- **复制与高可用**：物理/逻辑流复制、分区表与成熟 HA 生态（Patroni 等）

## 对用户价值

PostgreSQL 把关系模型的严谨性与现代数据类型、扩展机制结合，既能承载传统 OLTP 业务，也能支撑分析查询、GIS 与 AI 向量检索等混合负载。BSD 风格的 PostgreSQL License 允许商业部署与二次分发，社区文档、托管厂商与 ORM 生态极为成熟。对团队而言，它是 MySQL 之外最常被选中的「默认严肃数据库」，也是云厂商托管数据库（RDS、Cloud SQL 等）的常见底层引擎。

## 与替代方案

- 相比 **MySQL / MariaDB**，PostgreSQL 在复杂查询、扩展类型、标准 SQL 合规与并发模型上通常更完整；MySQL 在只读扩展与部分 Web 托管场景仍更常见。
- 相比 **SQLite**，PostgreSQL 面向多用户、网络访问与大规模并发，SQLite 更适合嵌入式、单文件与边缘本地存储。
- 相比 **MongoDB**，PostgreSQL 的 JSONB 可覆盖许多文档型需求，同时保留关系约束与事务；纯文档模型与水平分片极致场景 MongoDB 仍具优势。
- 相比 **云厂商专有数据库**，自建或自托管 PostgreSQL 换云成本低、行为可预期，但需要自行负责备份、升级与高可用。

## 适应人群

- 需要可靠事务型存储的后端开发者与全栈工程师。
- 负责 schema 设计、性能调优、备份复制与升级的 DBA 与运维工程师。
- 评估数据层架构、合规与长期许可成本的技术负责人与数据平台团队。

## 如何使用

### 前置条件

- 生产环境优先通过 [官方下载页](https://www.postgresql.org/download/) 或发行版包管理器安装预编译二进制，而非直接依赖 GitHub 镜像编译。
- 从源码构建需 GCC、GNU make、readline、zlib 等依赖；详见 [安装文档](https://www.postgresql.org/docs/current/installation.html)。
- macOS、Linux、Windows 均受支持；容器部署可使用官方 Docker 镜像或 Helm Chart。

### 安装方式

**macOS（Homebrew，推荐日常开发）**

```bash
brew install postgresql@17
brew services start postgresql@17
```

**Debian / Ubuntu（系统包）**

```bash
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl enable --now postgresql
```

**从本仓库源码构建（开发/定制编译）**

```bash
git clone https://github.com/postgres/postgres.git
cd postgres
./configure
make
sudo make install
```

### 首次运行

使用包管理器安装后，通常已有 `postgres` 系统用户与默认集群。创建数据库与用户示例：

```bash
sudo -u postgres psql -c "CREATE USER myapp WITH PASSWORD 'secret';"
sudo -u postgres psql -c "CREATE DATABASE myapp OWNER myapp;"
psql -h localhost -U myapp -d myapp
```

源码安装后需按文档执行 `initdb` 初始化数据目录，再启动 `postgres` 进程。

### 验证是否成功

```bash
psql -c "SELECT version();"
psql -c "CREATE TABLE t(id serial PRIMARY KEY, payload jsonb); INSERT INTO t(payload) VALUES('{\"ok\": true}'); SELECT * FROM t;"
```

能返回版本号并成功读写即表示核心功能正常。

### 常见坑 / 注意事项

- **GitHub 仅为镜像**：Issue/PR 不在此处理；安全与缺陷报告请走 [PostgreSQL 社区流程](https://www.postgresql.org/support/security/)。
- **版本与扩展兼容性**：大版本升级需 `pg_upgrade` 或逻辑迁移；PostGIS、pgvector 等扩展需匹配 PostgreSQL 主版本。
- **认证配置**：默认 `pg_hba.conf` 可能仅允许本地 peer 认证；远程访问需显式配置 host 规则与防火墙。
- **生产运维**：定期 `pg_dump`/物理备份、监控连接数与慢查询，并在大版本发布前阅读 [Release Notes](https://www.postgresql.org/docs/current/release.html)。

---

# superfile

> 颜值优先的现代终端文件管理器，多面板浏览、主题与插件，适合轻量日常文件操作。

- 页面：https://www.niceshare.site/github/superfile/
- 仓库：https://github.com/yorukot/superfile
- 官网：https://superfile.dev
- 语言：Go
- Stars：20637
- 许可证：MIT
- 标签：CLI、开发工具、工作流
- 收录：2026-07-27（更新于 2026-07-27）

## 项目介绍

superfile 是一款用 Go 与 [Bubble Tea](https://github.com/charmbracelet/bubbletea) 打造的现代终端文件管理器，官方定位是「Pretty fancy and modern」。它把侧栏、文件列表、进程、元数据、剪贴板与命令栏收进统一 TUI，强调观感与上手成本，适合不想离开终端、又只需完成轻量目录浏览与文件操作的日常场景。

## 核心特性

- **多面板布局**：侧栏、文件、进程、元数据、剪贴板与命令执行栏；可用快捷键切换焦点，支持多文件面板与预览开关
- **日常文件操作**：浏览、搜索、排序、钉选目录、显示/隐藏点文件；文件用系统默认应用打开
- **主题与快捷键**：可自定义主题与热键；Vim 用户可切换到 Vim 风格键位
- **插件扩展**：元数据（需 exiftool）、MD5 校验、[zoxide](https://github.com/ajeetdsouza/zoxide) 智能跳转等
- **跨平台安装**：macOS / Linux 一键脚本，Windows 支持 PowerShell / Winget / Scoop；启动命令为 `spf`

## 对用户价值

传统 GUI 文件管理器与终端工作流割裂，而许多终端文件管理器又偏「功能全家桶」、学习曲线陡。superfile 把美观、可读的 TUI 放在第一位，让复制、移动、预览、侧栏钉选等常见操作在终端内即可完成，减少在 Finder / 资源管理器与 shell 之间来回切换。若你的需求是轻量整理目录、快速定位路径，而不是复杂批处理或插件生态深挖，它往往比更重的方案更省心。

## 与替代方案

- 相比 [Yazi](https://github.com/sxyazi/yazi)：官方也承认 Yazi 等工具功能更全；superfile 胜在界面观感与上手简单，不适合作为「功能最强」的首选。
- 相比 [ranger](https://github.com/ranger/ranger) / [lf](https://github.com/gokcehan/lf)：后两者更偏极简或高度可脚本化；superfile 默认提供更现代的多面板 UI 与主题体系，脚本化与成熟度可能不如老牌方案。
- 相比 Finder、资源管理器或 [FileBrowser](https://github.com/filebrowser/filebrowser) 等 Web 方案：superfile 绑定终端与本地路径，无浏览器/多用户分享能力；适合开发者本机 CLI 工作流，不适合 Homelab 远程网盘场景。
- **边界**：Windows 官方标注「尚未完全支持」；图标依赖 Nerd Font；自动更新检查会访问 GitHub，可在配置中关闭。

## 适应人群

- 日常在 macOS / Linux 终端工作，希望用美观 TUI 代替频繁切换 GUI 文件管理器的开发者。
- 尝试过 ranger / yazi，但更看重开箱观感与较低学习成本的用户。
- 需要主题、热键与轻量插件（如 zoxide、元数据面板）来微调终端文件工作流的效率型用户。

## 如何使用

### 前置条件

- 操作系统：Linux、macOS；Windows 可用但官方标注尚未完全支持。
- 终端建议安装并启用 [Nerd Font](https://www.nerdfonts.com/)，否则图标可能显示异常。
- 可选：`exiftool`（元数据插件）、[zoxide](https://github.com/ajeetdsouza/zoxide)（智能跳转插件）。

### 安装方式

**macOS / Linux（官方一键脚本）：**

```bash
bash -c "$(curl -sLo- https://superfile.dev/install.sh)"
```

安装脚本源码见仓库 [`website/public/install.sh`](https://github.com/yorukot/superfile/blob/main/website/public/install.sh)。更多渠道见 [官方安装文档](https://superfile.dev/getting-started/installation/)。

**Windows：**

```powershell
# PowerShell
powershell -ExecutionPolicy Bypass -Command "Invoke-Expression ((New-Object System.Net.WebClient).DownloadString('https://superfile.dev/install.ps1'))"

# 或 Winget / Scoop
winget install --id yorukot.superfile
scoop install superfile
```

**从源码构建（需 Go）：**

```bash
git clone https://github.com/yorukot/superfile.git --depth=1
cd superfile
./build.sh          # macOS/Linux；Windows 可用 go build -o bin/spf.exe
sudo mv ./bin/spf /usr/local/bin
```

### 首次运行

在终端执行：

```bash
spf
```

按 `q` 或 `esc` 退出。建议先浏览 [官方教程](https://superfile.dev/getting-started/tutorial/)：`s` / `p` / `m` 切换侧栏、进程、元数据面板，`n` / `w` 开闭文件面板，`j`/`k` 或方向键移动，`enter`/`l` 进入，`h` 返回上级。Vim 用户请按文档改为 Vim 版热键配置。

### 验证是否成功

- 执行 `spf` 后出现多面板 TUI，图标与文字渲染正常。
- 能进入/退出目录、用 `/` 搜索当前目录，并按 `q` 干净退出。
- 若启用 zoxide 插件，按 `z` 可打开跳转搜索；元数据面板在聚焦后能显示目录大小等信息。

### 常见坑 / 注意事项

- **图标乱码**：安装 Nerd Font 并在终端模拟器中启用该字体。
- **渲染错乱**：将 locale 设为 UTF-8；必要时设置 `RUNEWIDTH_EASTASIAN=0`；Windows 可尝试 `chcp 65001`。更多见 [Troubleshooting](https://superfile.dev/troubleshooting/)。
- **自动更新提示**：默认约每 24 小时检查 GitHub 新版本；可在配置中将 `auto_check_update` 设为 `false`。
- **Windows 完整度**：部分能力仍在完善中，生产主力机建议优先 macOS/Linux。
- 卸载：macOS/Linux 可用官方 `uninstall.sh`；Windows 对应 `uninstall.ps1`（见仓库 README）。

---

# OpenWork

> 开源 Claude Cowork 替代方案：跨 Agent 共享技能与 MCP 的桌面 AI 工作流应用。

- 页面：https://www.niceshare.site/github/openwork/
- 仓库：https://github.com/different-ai/openwork
- 官网：https://openworklabs.com
- 语言：TypeScript
- Stars：20151
- 许可证：MIT
- 标签：Agent、工作流、开发工具
- 收录：2026-08-02（更新于 2026-08-02）

## 项目介绍

OpenWork 是 Different AI 推出的开源桌面应用，定位为 Claude Cowork 与 Codex 的跨平台替代方案（macOS / Windows / Linux），底层由 OpenCode 驱动。你可以把一套技能、MCP 与已连接服务，通过单一 OpenWork MCP 复用到 Codex、Claude Code、Cursor 等兼容 Agent；桌面端是可选工作区，团队侧则可用 OpenWork Den 做能力发布与访问管控。

## 核心特性

- **跨 Agent 复用**：添加一次 OpenWork MCP，即可在多款 Agent 中搜索并执行同一批能力（`search_capabilities` / `execute_capability`）
- **可选桌面工作区**：需要专注界面时用桌面 App；也可只在现有 Agent 里使用，不必强制安装桌面端
- **OpenWork Den 管控面**：统一配置推理提供商、成员与团队权限、桌面策略与可安装版本
- **技能与插件市场**：发布 skills / plugins，按组织、团队或个人分配；可导入 Anthropic 兼容插件并暴露其远程 MCP
- **Agent 一键安装**：把官方安装提示词贴进 Claude Code / Cursor / Codex 等，即可完成安装、建工作区并打开就绪状态

## 对用户价值

把「在某个 Agent 里配好的技能与连接」从单机、单工具里解放出来，变成可共享的组织能力。个人用户能一次配置、多端复用；小团队可以把 Google Workspace、Microsoft 365 等连接与内部技能统一分发，而不必在每人的 Cursor / Claude Code 里重复粘贴配置。对需要策略管控（本地模型、应用版本）的组织，Den 提供集中管理入口，降低影子 IT 式散装 Agent 配置的成本。

## 与替代方案

- 相比 **Claude Cowork**：OpenWork 强调开源与跨 Agent；Cowork 深度绑定 Anthropic 产品体验与账号体系。
- 相比 **OpenCode**：OpenCode 是编码 Agent 运行时本身；OpenWork 在其之上做工作流共享、MCP 聚合与组织管控，二者互补而非简单替代。
- 相比 **Dify / n8n**：后两者偏可视化应用或通用自动化编排；OpenWork 面向「已有 AI Agent 客户端」的能力共享与桌面协作，而不是从零搭低代码平台。
- 若你只需单人、单工具里写代码，直接用 Claude Code / Cursor / OpenCode 可能更轻；需要跨工具与跨同事复用同一套能力时，OpenWork 更合适。

## 适应人群

- 同时使用多种 Agent（Cursor、Codex、Claude Code 等），厌倦在各处重复配置技能与 MCP 的个人开发者。
- 希望把内部插件、连接与推理配额统一分发给成员的小团队管理员。
- 在评估开源 Cowork 替代方案、关注跨平台桌面与组织策略的技术决策者。

## 如何使用

### 前置条件

- 支持的操作系统：macOS、Windows 或 Linux。
- 至少一个兼容 MCP 的 AI Agent（如 Codex、Claude Code、Cursor、OpenCode），或计划安装官方桌面应用。
- 可访问 [openworklabs.com](https://openworklabs.com)；添加 MCP 后需在浏览器完成登录并选择组织。
- 参与源码开发时：Node.js + pnpm（见仓库本地开发说明）。

### 安装方式

**桌面应用（推荐终端用户）：** 从 [官方下载页](https://openworklabs.com/download) 安装对应平台包。

**用现有 AI Agent 安装（官方提示词）：** 将以下内容粘贴到 Claude Code、Cursor、Codex 等可执行本机命令的 Agent：

```text
Install OpenWork on my computer, set up my first workspace, and open it ready to use. Follow the steps in https://openworklabs.com/start.md?v=hero
```

**仅接入 OpenWork MCP（不强制桌面端）：**

```bash
# Codex
codex mcp add openwork --url https://api.openworklabs.com/mcp/agent

# Claude Code
claude mcp add --transport http openwork https://api.openworklabs.com/mcp/agent
```

OpenCode 在 `opencode.json` 中配置：

```json
{
  "mcp": {
    "openwork": {
      "type": "remote",
      "enabled": true,
      "url": "https://api.openworklabs.com/mcp/agent",
      "oauth": {}
    }
  }
}
```

任意 MCP 客户端也可直接使用远程地址：`https://api.openworklabs.com/mcp/agent`。

**本地开发（贡献者）：**

```bash
pnpm dev
# 多 worktree 并行开发时：
pnpm dev:worktree
```

### 首次运行

1. 安装桌面端或完成 Agent 侧安装提示词后，创建首个 workspace。
2. 在 Agent 中添加 OpenWork MCP，按提示完成浏览器登录并选择组织。
3. 用 `search_capabilities` 查看可用能力，再用 `execute_capability` 执行一项你已分配的技能或连接，确认链路通畅。
4. 团队场景下进入 OpenWork Den，邀请成员、发布技能/插件并按组织或个人分配。

### 验证是否成功

- 桌面端能正常打开工作区；或 Agent 侧 MCP 列表中出现 `openwork`。
- 登录后能列出组织分配的能力；执行一项无害的 capability 返回成功而非鉴权失败。
- 开发模式下启动日志出现类似 `[openwork] dev profile=... cdp=http://127.0.0.1:...` 的横幅。

### 常见坑 / 注意事项

- **许可证分层**：仓库主体多为 MIT，但 `/ee` 目录为 Fair Source；二次分发或商用前请核对 `LICENSE` 与 `ee/LICENSE`。
- **MCP 需登录**：添加远程 MCP 后会打开浏览器做 OAuth/组织选择，跳过登录会导致能力列表为空。
- **开发 profile 与钥匙串**：`pnpm dev:worktree` 默认 `OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1`，避免 macOS 钥匙串弹窗卡住 Electron；若要用系统钥匙串需显式设为 `0`。
- **多实例锁**：第二个实例抢不到同一 profile 锁会直接退出；并行调试请用不同 `OPENWORK_DEV_PROFILE` 或 `dev:worktree`。
- **文档入口**：[官方文档](https://openworklabs.com/docs) 与下载页更新可能快于 README，安装前建议对照官网最新步骤。

---

# MDX

> 在 Markdown 中无缝嵌入 JSX 的可编写格式，可导入 React 等组件，面向组件时代的长文内容。

- 页面：https://www.niceshare.site/github/mdx/
- 仓库：https://github.com/mdx-js/mdx
- 官网：https://mdxjs.com
- 语言：JavaScript
- Stars：19617
- 许可证：MIT
- 标签：开发工具、前端、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

MDX 是由 [unified](https://github.com/unifiedjs/unified) 生态维护的可编写格式，口号是「Markdown for the component era」——在保留 Markdown 写作体验的同时，允许在文档中直接写 JSX、导入 React/Vue/Preact 等组件，并在正文里嵌入图表、提示框、交互演示等 UI。本仓库是 MDX 编译器与生态 monorepo，包含将 MDX 编译为 JavaScript 的核心包 `@mdx-js/mdx`，以及面向 webpack、Rollup/Vite、esbuild 等打包器的官方集成；站点 [mdxjs.com](https://mdxjs.com) 提供格式说明、Playground 与完整接入指南。

## 核心特性

- **Markdown + JSX 混写**：在 `.mdx` 文件中同时使用标题、列表等 Markdown 语法与 JSX 标签，可在 frontmatter 导出变量并在正文中引用
- **组件导入与嵌入**：可 `import` 本地或 npm 包中的 React/Vue 等组件，把交互式图表、代码演示、Alert 等直接写进长文
- **unified 编译管线**：基于 remark/rehype 生态，将 MDX 编译为可在目标 JSX 运行时执行的 JavaScript 模块
- **多打包器官方集成**：提供 `@mdx-js/loader`（webpack/Next.js）、`@mdx-js/rollup`（Rollup/Vite）、`@mdx-js/esbuild`（esbuild/Bun）等接入方式
- **多 JSX 运行时**：默认面向 React，亦支持 Preact、Vue、Solid、Svelte 等，通过 `jsxImportSource` 配置切换

## 对用户价值

纯 Markdown 适合静态文档，但技术博客与产品文档 increasingly 需要可交互示例；纯 JSX/TSX 又会让非工程写作者望而却步。MDX 把「写作层」与「组件层」解耦：作者继续用熟悉的 Markdown 工作流，开发者提供可复用组件库，读者在单页内获得连贯的阅读与交互体验。Astro、Next.js、Gatsby、Starlight 等框架均内置或推荐 MDX 作为内容格式，掌握 MDX 编译原理有助于排查构建错误、定制 remark 插件，或在无框架场景下用 `@mdx-js/mdx` 直接编译内容。

## 与替代方案

- 相比 [remark-react](https://github.com/remarkjs/remark-react) / [rehype-react](https://github.com/rehypejs/rehype-react) 等底层工具，MDX 提供**一等公民的 JSX 语法**与完整编译器，作者无需手写 AST 转换即可在 Markdown 中写组件；底层方案更灵活但集成成本更高。
- 相比 [Markdoc](https://markdoc.dev/)（Stripe 推出），两者都支持在标记语言中嵌入组件；MDX 使用标准 JSX 语法、与 React 生态绑定更深，Markdoc 采用自定义标签语法，更适合需要严格内容/schema 约束的企业文档。
- 相比直接在框架中使用 Markdown（无 JSX），MDX 适合需要在正文中**嵌入可交互 UI** 的场景；若内容纯静态、无需组件，普通 `.md` + 框架 Content Collections 往往更简单。
- 相比在 `.astro` / `.vue` 单文件组件中写内容，MDX 让**非框架写作者**也能贡献带组件的长文，并与 npm 组件库自然集成。
- 边界说明：MDX 编译产物依赖 JSX 运行时，不适合「零 JavaScript」的纯静态站点主体；安全上需警惕 MDX 中的任意 JS 执行，生产环境应限制可导入模块与编译选项（见官方 [Security](https://mdxjs.com/getting-started/#security) 说明）。

## 适应人群

- 维护技术博客、changelog 或产品文档，希望在 Markdown 正文中嵌入 Demo、图表、Tabs 等交互组件的前端开发者。
- 使用 Astro、Next.js、Gatsby 等内容框架，需要理解或定制 MDX 编译链路的工程团队。
- 技术写作者与 Developer Advocate，希望用 Markdown 写作又能在不离开文档文件的情况下调用设计系统组件。

## 如何使用

### 前置条件

- Node.js 16+（官方 `@mdx-js/*` 包为 ESM only，需现代 Node 环境）。
- 项目已支持 JSX：React、Preact、Vue 等任一 JSX 运行时均可。
- 选定打包工具：Vite/Rollup、webpack/Next.js 或 esbuild，对应安装官方集成包。

### 安装方式

**方式一：Vite / Rollup 项目（常见）**

```bash
npm install @mdx-js/rollup @mdx-js/react
```

在 `vite.config.js` 或 `rollup.config.js` 中注册插件（React 为默认 JSX 运行时）：

```js
import mdx from '@mdx-js/rollup'

export default {
  plugins: [mdx(/* options */)]
}
```

**方式二：webpack / Next.js**

```bash
npm install @mdx-js/loader @mdx-js/react
```

按 [官方 Next.js 集成文档](https://mdxjs.com/packages/loader/) 配置 `module.rules` 或 Next.js MDX 选项。

**方式三：无打包器，使用核心编译器**

```bash
npm install @mdx-js/mdx
```

适合 Node 脚本或自定义构建管线，通过 `@mdx-js/mdx` 的 `compile` / `evaluate` API 处理 `.mdx` 文件。

TypeScript 项目可额外安装类型支持：

```bash
npm install @types/mdx
```

### 首次运行

1. 在项目中新建 `hello.mdx`，写入 Markdown 与 JSX 混合内容，例如导入一个简单组件并在正文使用。
2. 在入口文件或路由中 `import Hello from './hello.mdx'`，按所选 JSX 运行时渲染（React 中即 `<Hello />`）。
3. 启动开发服务器，访问引用该 MDX 的页面，确认编译与热更新正常。

也可先在 [Playground](https://mdxjs.com/playground/) 在线试验语法，再落地到本地项目。

### 验证是否成功

- 开发服务器启动无 MDX 编译报错，目标页面能渲染 Markdown 与嵌入组件。
- 修改 `.mdx` 文件后热更新生效，组件 props 变更能反映到页面。
- 生产构建（如 `npm run build`）成功，产物中 MDX 页可正常访问。
- 若使用 TypeScript，`import Post from './post.mdx'` 应能推断 `MDXProps` 类型（需 `@types/mdx` 与框架 JSX 类型声明）。

### 常见坑 / 注意事项

- **ESM only**：`@mdx-js/*` 包仅提供 ESM，CommonJS 项目需 `"type": "module"` 或动态 `import()`，详见各包 README。
- **JSX 运行时配置**：使用 Preact、Vue、Solid 等非 React 运行时，须在编译选项中设置 `jsxImportSource`，并安装对应 `@mdx-js/react` 替代包（如 `@mdx-js/vue`）。
- **安全**：MDX 可执行任意 JavaScript，勿对不可信来源的 MDX 直接 `evaluate`；生产环境限制 `import` 白名单，阅读官方 Security 章节。
- **编辑器支持**：VS Code 可安装 [mdx-js/mdx-analyzer](https://github.com/mdx-js/mdx-analyzer) 获得语法高亮与类型提示。
- **求助渠道**：查阅 [mdxjs.com 文档](https://mdxjs.com/docs/getting-started/)、[GitHub Discussions](https://github.com/mdx-js/mdx/discussions)，或 unified 社区 [OpenCollective](https://opencollective.com/unified) 支持渠道。

---

# OpenFang

> Rust 开源 Agent 操作系统，单二进制部署，内置 Hands 自主任务与 40+ 消息频道适配。

- 页面：https://www.niceshare.site/github/openfang/
- 仓库：https://github.com/RightNow-AI/openfang
- 官网：https://www.openfang.sh/
- 语言：Rust
- Stars：17959
- 许可证：Apache-2.0
- 标签：Agent、自动化、开发工具
- 收录：2026-07-03（更新于 2026-07-03）

## 项目介绍

OpenFang 是一款用 **Rust 从零构建的开源 Agent 操作系统**：不是聊天机器人框架，也不是围绕 LLM 的 Python 封装。它把编排内核、工具运行时、记忆、频道适配与桌面端打成**约 32MB 的单二进制**，一条命令即可启动 Dashboard（默认 `http://localhost:4200`）。核心创新是 **Hands**——可独立运行、按日程触发的自主能力包，让 Agent 在后台持续调研、获客、监控、发帖或执行浏览器工作流，而不必等你每次输入提示词。

## 核心特性

- **Hands 自主能力包**：内置 Clip、Lead、Collector、Predictor、Researcher、Twitter、Browser 等 7 套 Hand，含 `HAND.toml` 清单、多阶段 System Prompt、`SKILL.md` 领域知识与敏感操作审批门
- **14 crate 模块化内核**：覆盖 kernel 编排、runtime（3 种 LLM 驱动、53 工具、WASM 沙箱、MCP/A2A）、API（140+ REST/WS/SSE、OpenAI 兼容接口）、memory（SQLite + 向量）、channels、skills、desktop（Tauri 2.0）等
- **40 个频道适配器**：Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Teams、飞书、Mastodon、Webhooks 等，支持按频道模型覆盖、DM/群组策略与限流
- **16 层安全体系**：WASM 双计量沙箱、Merkle 审计链、污点追踪、Ed25519 签名清单、SSRF 防护、提示注入扫描、循环熔断等
- **迁移与扩展**：`openfang-migrate` 支持从 OpenClaw、LangChain、AutoGPT 迁移；FangHub 可发布自定义 Hand 与技能

## 对用户价值

若你需要的是**「Agent 替我干活」**而非「我打字它才回」，OpenFang 的 Hands 模型更贴近生产场景：例如 Researcher 跨源调研并输出引用报告，Lead 按 ICP 每日发现线索，Browser Hand 在**强制购买审批**下完成网页自动化。单二进制降低部署与运维成本；相比 Python 系编排框架，官方基准强调更快的冷启动、更小的安装体积与更完整的频道/安全能力。Dashboard + CLI + 可选 Tauri 桌面端，适合在个人机器或小团队内网长期常驻。

## 与替代方案

- 相比 [OpenClaw](https://github.com/openclaw/openclaw)，OpenFang 更强调 **Rust 单体二进制、Hands 定时自主任务与 16 层安全栈**；OpenClaw 侧重多频道个人助理 Gateway 与伴侣应用生态。OpenFang 提供从 OpenClaw 的迁移引擎，二者可对照评估。
- 相比 [ZeroClaw](https://github.com/zeroclaw-labs/zeroclaw)，二者同为 Rust 单二进制路线；ZeroClaw 偏**极简个人助理基础设施**（更小体积、更快冷启动），OpenFang 偏**完整 Agent OS**（内置 Hands、更多频道适配器、WASM 沙箱与审计链）。选型取决于你是否需要开箱的自主 Hand 与更重安全/编排能力。
- 相比 [CrewAI](https://github.com/crewAIInc/crewAI)、[AutoGen](https://github.com/microsoft/autogen)、[LangGraph](https://github.com/langchain-ai/langgraph) 等 **Python 多 Agent 编排框架**，OpenFang 是**可常驻运行的系统级运行时**（频道、记忆、工具、沙箱、API 一体），而非库级编排；若团队主力栈是 Python 且只需脚本内编排，框架可能更轻。
- 相比 [Cline](https://github.com/cline/cline)、[Aider](https://github.com/Aider-AI/aider) 等 **IDE/终端结对编程**工具，OpenFang 主战场是**后台自主任务、多渠道触达与浏览器/获客等工作流**，不是编辑器深度集成。

## 适应人群

- 希望 Agent **按日程自主运行**（调研、线索、监控、社媒等），并能在 Dashboard 查看状态的个人或小团队。
- 需要 **多消息频道统一接入**、且关注沙箱、审计与审批门的工程团队。
- 已使用 OpenClaw / LangChain / AutoGPT，想评估迁移到 Rust 单体运行时的开发者。
- 愿意接受 **pre-1.0** 节奏、可固定 commit 后再上生产的早期采用者。

## 如何使用

### 前置条件

- **操作系统**：支持官方安装脚本的平台（macOS / Linux；Windows 见下方 PowerShell 路径）。
- **Node.js >= 18**：仅在使用 WhatsApp Web Gateway（QR 码扫码）等 Node 桥接组件时需要。
- **LLM 访问**：按 `openfang init` 向导配置提供商与 API Key；支持 27+ 提供商（见官方文档 Model Catalog）。
- **版本预期**：项目仍处 pre-1.0，小版本间可能有破坏性变更；生产环境建议固定到特定 commit，升级前阅读 [Releases](https://github.com/RightNow-AI/openfang/releases) 与 [文档](https://openfang.sh/docs)。

### 安装方式

macOS / Linux：

```bash
curl -fsSL https://openfang.sh/install | sh
openfang init
openfang start
# Dashboard: http://localhost:4200
```

Windows（PowerShell）：

```powershell
irm https://openfang.sh/install.ps1 | iex
openfang init
openfang start
```

### 首次运行

完成 `openfang init` 后启动服务，在 Dashboard 配置模型与频道。激活内置 Hand 示例：

```bash
openfang hand list
openfang hand activate researcher
openfang hand status researcher

# 按日程运行线索 Hand
openfang hand activate lead

# 暂停但保留状态
openfang hand pause lead
```

自定义 Hand 可编写 `HAND.toml` 并发布到 FangHub；从其他框架迁移见官方 `openfang-migrate` 文档。

### 验证是否成功

- `openfang start` 后浏览器访问 `http://localhost:4200`，Dashboard 可加载。
- `openfang hand list` 列出 7 个内置 Hand；`openfang hand status <name>` 显示运行状态。
- 激活 Researcher 等 Hand 后，在 Dashboard 或配置的频道（如 Telegram）检查是否有任务输出。

### 常见坑 / 注意事项

- **pre-1.0 稳定性**：README 明确提示功能完整但仍有粗糙边缘；不要在未固定版本的情况下直接用于关键生产。
- **敏感操作审批**：Browser Hand 等涉及消费的流程有强制审批门；Twitter Hand 默认走审批队列，避免误发帖。
- **WhatsApp Web Gateway**：需单独在 `packages/whatsapp-gateway` 执行 `npm install` 并启动 Node 网关，同时在 `config.toml` 配置 `[channels.whatsapp] mode = "web"` 及 `WHATSAPP_WEB_GATEWAY_URL`。
- **密钥管理**：API Key 通过 init/配置写入本地；勿将凭据提交到 Git；利用内置 Secret Zeroization 与能力门控，仍建议最小权限原则。
- **许可证**：GitHub 元数据为 Apache-2.0；README 对比表中部分条目标注 MIT，以仓库 License 文件与 API 为准。

---

# iTerm2

> macOS 上功能最丰富的终端模拟器，集成 tmux、Shell 感知、会话恢复与 AI 聊天。

- 页面：https://www.niceshare.site/github/iterm2/
- 仓库：https://github.com/gnachman/iterm2
- 官网：https://iterm2.com/
- 语言：Objective-C
- Stars：17713
- 许可证：GPL-2.0
- 标签：开发工具、CLI、自动化
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

iTerm2 是 macOS 上长期使用的终端模拟器，在系统自带 Terminal 之上提供 tmux 原生窗口、Shell 深度感知、会话持久化、触发器自动化与内置 AI 聊天等能力。它把「远程开发、多会话管理、终端内可视化」整合进同一套界面，是不少 Mac 开发者换机后最先安装的工具之一。

## 核心特性

- **tmux 集成**：`tmux -CC` 将 tmux 窗口映射为原生 macOS 窗口/标签；崩溃、SSH 断连或升级后仍可恢复会话，并支持多人附着同一会话
- **Shell Integration**：追踪命令、目录、主机名与用户；支持 SCP 点击下载、拖拽上传、按主机记录命令历史与「frecency」最近目录
- **会话恢复**：Shell 运行在独立 server 进程；iTerm2 崩溃或重启后可重连到原会话状态
- **AI Chat**：内置 LLM 聊天窗口，可关联终端会话获取上下文、代为执行命令或注解输出
- **自动化与扩展**：正则 Triggers、Python Scripting API、可配置状态栏（Git 分支、CPU/内存、自定义组件）
- **效率交互**：全局热键窗口、按主机/目录/命令自动切换 Profile、Inline 图片（imgcat）、Instant Replay 与 Vim 式 Copy Mode

## 对用户价值

系统 Terminal 适合偶尔开 shell，但难以应对多 SSH 会话、tmux 可视化与复杂自动化。iTerm2 把远程协作、会话保活、目录/主机上下文与终端内 AI 放在同一应用里，减少在 tmux 文本界面、多个窗口与外部工具之间切换。对重度命令行用户，它是「开箱即用的高配终端」而非再搭一套插件生态。

## 与替代方案

- 相比 **macOS 自带 Terminal**，iTerm2 提供分屏、Profile、tmux 集成、触发器、Python API 与 AI Chat，功能深度明显更高；代价是体积更大、学习曲线更陡。
- 相比 **Warp** 等现代终端，iTerm2 开源可审计（GPL）、可自编译，Python 自动化与 tmux 集成更成熟；Warp 等则在块编辑、AI 原生 UI 上更激进，但闭源且平台策略不同。
- 相比 **Alacritty / Kitty** 等跨平台 GPU 终端，iTerm2 专注 macOS 原生体验与 tmux/Shell 集成；若你需要 Linux/Windows 统一配置或极致轻量，后者更合适。
- 若只需在 VS Code / Cursor 内置终端里跑命令，不必强行迁移；iTerm2 更适合独立管理大量 SSH、tmux 与自动化脚本的场景。

## 适应人群

- 每天在 macOS 上管理多个 SSH、tmux 或远程开发会话的后端与 DevOps 工程师。
- 希望用 Triggers、Python API 或 Shell Integration 做终端自动化与上下文感知的效率型开发者。
- 需要会话持久化、协作附着或终端内 AI 辅助排查输出的 Mac 命令行重度用户。

## 如何使用

### 前置条件

- **macOS**（iTerm2 仅支持 Mac，无 Windows/Linux 官方版本）
- 普通使用：从官网下载安装包即可，无需 Xcode
- 从源码构建：需 macOS 开发环境；`make setup` 会按需安装 Homebrew、Xcode、Rust 等（交互式确认）

### 安装方式

- **推荐：官网安装包**（稳定版）：

从 [iterm2.com/downloads](https://iterm2.com/downloads.html) 下载 `.zip`，拖入「应用程序」文件夹。

- **尝鲜：Nightly 构建**：

[iterm2.com/nightly/latest](https://iterm2.com/nightly/latest)

- **从源码构建**（贡献者 / 高级用户）：

```bash
git clone https://github.com/gnachman/iTerm2.git
cd iTerm2
make setup          # 首次：安装依赖（交互式）
make paranoid-deps  # 编译 OpenSSL、libsixel 等原生依赖
make Development
make run
```

Universal 二进制：`UNIVERSAL=1 make Development`

### 首次运行

启动 iTerm2 后创建或导入 Profile（颜色、字体、快捷键）。若使用远程开发，建议安装 [Shell Integration](https://iterm2.com/documentation-shell-integration.html) 脚本以启用目录追踪与 frecency。使用 tmux 时可尝试 `tmux -CC` 体验原生窗口模式。

### 验证是否成功

确认新标签可正常打开 shell、分屏与 Profile 切换可用。若已装 Shell Integration，在提示符处应能看到状态标记；`tmux -CC` 下 tmux 窗口应显示为独立 macOS 窗口。源码构建后 `make run` 应能启动 Development 配置的应用。

### 常见坑 / 注意事项

- **仅 macOS**：无法在 Linux/Windows 上运行；跨平台团队需另选终端。
- **许可**：仓库标注 GPL-2.0（GitHub）；官网 README 亦提及 GPLv3，二次分发或嵌入需自行核对 LICENSE。
- **Issue 跟踪在 GitLab**：Bug 报告见 [iterm2.com/bugs](https://iterm2.com/bugs)，主 issue 列表在 [GitLab](https://gitlab.com/gnachman/iterm2/issues)，与 GitHub 仓库并存。
- **源码构建**：Development 构建可能不如正式版稳定；切换 Xcode 版本后需重跑 `make paranoid-deps`。
- **AI Chat** 涉及 LLM 接入与隐私策略，启用前阅读 [官方文档](https://iterm2.com/documentation.html) 中的相关说明。

---

# Gas Town

> 面向 Claude Code 等多 Agent 的工作区编排器，用 Git Hook 与 Beads 持久化任务状态。

- 页面：https://www.niceshare.site/github/gastown/
- 仓库：https://github.com/gastownhall/gastown
- 语言：Go
- Stars：16585
- 许可证：MIT
- 标签：Agent、AI 编程、CLI
- 收录：2026-07-06（更新于 2026-07-06）

## 项目介绍

Gas Town（`gt`）是一款**多 Agent 工作区编排器**，让你在同一个 Town 里协调 Claude Code、GitHub Copilot、Codex、Gemini 等编码 Agent 并行处理不同任务。它用 **Git worktree Hooks** 与 **Beads** 账本持久化工作状态，Agent 会话重启后上下文不丢，官方称可稳定扩展到 20–30 个 Agent。入口是 **Mayor**——一个带全量工作区上下文的协调会话，你从这里下达目标即可。

## 核心特性

- **Town / Rig 分层**：Town 为工作区根目录（如 `~/gt/`），Rig 包裹单个 Git 仓库及其 Agent 群
- **Polecats 工人 Agent**：带持久身份、会话随任务结束；Hooks 用 git worktree 保存产出，崩溃可恢复
- **Convoys 任务编组**：将多个 Bead 打包派发给 Agent；`mountain` 标签支持自主停滞检测与跳过逻辑
- **Molecules 工作流模板**：TOML 定义多步流程，支持轻量 wisps 与带检查点的 poured wisps
- **三层看门狗**：Witness（单 Rig 生命周期）、Deacon（全局巡检）、Dogs（基础设施维护）
- **Refinery 合并队列**：Polecat 完成后经 Bors 风格队列批量验证并合并到 main
- **Seance 会话延续**：从 `.events.jsonl` 发现前序会话，向「前任」Agent 追问上下文
- **Wasteland 联邦协作**：通过 DoltHub 跨 Town 认领任务、提交证据并积累声誉

## 对用户价值

当你从「单 Agent 结对编程」升级到「多 Agent 并行改多个仓库」时，最难的是**协调、状态丢失与合并冲突**。Gas Town 把任务拆成 Bead、用 Convoy 派发、用 Hooks 落盘，再配合 Refinery 统一合并，减少人工盯梢。Escalation（`gt escalate`）把阻塞按严重级别路由给 Deacon、Mayor 或 Overseer；Scheduler 可限制并发派发，缓解 API 限流。对重度 Claude Code / Copilot CLI 用户，这是把「多终端多窗口」升级为**可恢复、可审计**工作流的基础设施。

## 与替代方案

- 相比 [Aider](https://github.com/Aider-AI/aider)、[Cline](https://github.com/cline/cline) 等**单会话 IDE/终端结对**工具，Gas Town 专注**多 Agent 编排与跨仓库状态持久化**，不替代编辑器集成，而是管理 Agent 舰队与合并队列。
- 相比 [OpenCode](https://github.com/sst/opencode) 等**轻量多模型终端**，Gas Town 更重**组织架构**（Mayor、Rig、Polecat、Witness）与 **Beads/Git 工作流**，适合长期并行而非单次对话。
- 相比 [n8n](https://github.com/n8n-io/n8n)、[Dify](https://github.com/langgenius/dify) 等**可视化工作流平台**，Gas Town 是**开发者本地 CLI 运行时**，依赖 tmux、git worktree、Dolt 等，上手成本更高，但 Agent 直接在代码库上操作。
- 若只需 1–2 个 Agent 偶尔改 bug，Gas Town 可能过重；若已稳定使用 Claude Code CLI 并想规模化派发，它填补「多 Agent 混沌」这一空白。

## 适应人群

- 已日常使用 **Claude Code / Copilot CLI / Codex CLI**，希望并行跑多个编码 Agent 的开发者。
- 维护**多仓库、多分支**并行开发，需要任务账本、合并队列与崩溃恢复的团队。
- 愿意投入学习 Town/Rig/Polecat/Beads 术语，追求 **20+ Agent 可运维** 的进阶用户。
- 对 **Wasteland 跨 Town 协作** 或自托管 Docker Compose 仪表盘有兴趣的实验型玩家。

## 如何使用

### 前置条件

- **Go 1.25+**、**Git 2.25+**（worktree）、**Dolt 2.0.7+**、**beads (bd) 0.55.4+**、**sqlite3**、**tmux 3.0+**（推荐）
- 至少一种 Agent 运行时：**Claude Code CLI**（默认）；可选 Codex CLI、GitHub Copilot CLI
- macOS 上 `go install` 可能因未签名被 SIGKILL，优先用 Homebrew 安装

### 安装方式

```bash
# 推荐（macOS）
brew install gastown

# 或 npm
npm install -g @gastown/gt

# Linux 源码
go install github.com/steveyegge/gastown/cmd/gt@latest
export PATH="$PATH:$HOME/go/bin"
```

Docker Compose 路径见仓库 README；完整依赖说明见 [docs/INSTALLING.md](https://github.com/gastownhall/gastown/blob/main/docs/INSTALLING.md)。

### 首次运行

```bash
gt install ~/gt --git
cd ~/gt

# 添加项目 Rig 与个人 Crew 工作区
gt rig add myproject https://github.com/you/repo.git
gt crew add yourname --rig myproject
cd myproject/crew/yourname

# 启动 Mayor（主协调界面）
gt mayor attach
```

### 验证是否成功

```bash
cd ~/gt
gt config agent list    # 应列出已配置的 Agent 运行时
gt mayor attach         # 能进入 Mayor 会话并响应指令
```

在 Rig 内派发任务后，检查 `gt convoy list` 与 Hooks worktree 是否生成预期文件；合并流程可走 `gt done` 触发 Refinery。

### 常见坑 / 注意事项

- macOS 勿仅用 `go install` 装 `gt`，用 **brew** 或 `make build` 自签构建。
- 依赖链较长（Dolt、beads、tmux、Claude Code 等），缺一项会导致子命令静默失败，先对照 README Prerequisites。
- 多 Agent 并行会放大 **API 配额与费用**；可配置 `scheduler.max_polecats` 限制并发派发。
- 生产密钥与 `~/gt` 工作区应单独备份；Wasteland 联邦功能仍在演进，部署前阅读 [WASTELAND.md](https://github.com/gastownhall/gastown/blob/main/docs/WASTELAND.md)。

---

# Pinia

> Vue 官方推荐的状态管理库，以 Store 为核心提供类型安全、模块化、轻量的全局状态方案。

- 页面：https://www.niceshare.site/github/pinia/
- 仓库：https://github.com/vuejs/pinia
- 官网：https://pinia.vuejs.org
- 语言：TypeScript
- Stars：14615
- 许可证：MIT
- 标签：开发工具、前端、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Pinia 是 [Vue.js 官方](https://vuejs.org/guide/scaling-up/state-management.html#pinia) 推荐的状态管理库，由 Vue Router 作者维护，定位为 Vuex 的继任者。它以独立的 Store 为单位组织状态，API 直观、TypeScript 友好，并完整支持 Vue DevTools。当前主分支面向 Vue 3；维护 Vue 2 项目请使用仓库 [v2 分支](https://github.com/vuejs/pinia/tree/v2)。Pinia 同时提供 [Nuxt 模块](https://pinia.vuejs.org/ssr/nuxt.html)，可在 SSR 场景下开箱集成。

## 核心特性

- **直观 API**：通过 `defineStore` 定义 Store，state、getters、actions 结构清晰，心智负担低于传统 Vuex 的 mutations 与 modules 嵌套
- **类型安全**：TypeScript 一等公民，Store 定义与 `storeToRefs` 等工具在 IDE 中可获得完整类型推导
- **模块化设计**：每个 Store 独立文件、按需导入，通过 [组合多个 Store](https://pinia.vuejs.org/cookbook/composing-stores.html) 替代动态模块，兼顾灵活与类型安全
- **DevTools 集成**：支持 Vue DevTools 调试时间旅行、状态快照与 action 追踪
- **轻量可扩展**：包体积极小，同时支持 Options API 与 Composition API；提供插件机制扩展持久化、日志等能力

## 对用户价值

组件间共享用户会话、购物车、主题偏好等状态时，仅靠 props 逐层传递或事件总线很快变得难以维护。Pinia 把全局状态收敛到命名清晰的 Store，组件通过 `useXxxStore()` 按需订阅，避免「上帝对象」式单例。相比 Vuex，省去 mutations 样板代码，actions 可直接异步请求并修改 state；相比在组件内用 `ref`/`reactive` 手写全局单例，Pinia 提供 DevTools、SSR 与 Nuxt 官方集成，更适合中大型 Vue 应用。

## 与替代方案

- 相比 [Vuex](https://vuex.vuejs.org/)，Pinia 是 Vue 官方文档明确推荐的继任方案：无 mutations、模块无需嵌套注册，TypeScript 体验更好；Vuex 4 仍可用于 Vue 3 遗留项目，但新项目应优先 Pinia。
- 相比 [Redux](https://redux.js.org/) / [Zustand](https://github.com/pmndrs/zustand)（React 生态），Pinia 深度绑定 Vue 响应式系统，与 `setup()`、`computed` 自然协作；跨框架选型时勿强行类比，应按技术栈选择。
- 相比组件内 [provide/inject](https://vuejs.org/guide/components/provide-inject.html) 或 Composable 单例，Pinia 适合**跨路由、跨深层组件树**的共享状态；仅限父子或局部子树的轻量状态，可能不必引入全局 Store。
- 边界说明：Pinia 不提供动态模块（出于类型安全考虑）；需要「多实例」场景时，应创建多个独立 Store 或在 action 中传参，而非复刻 Vuex 动态 register 模式。

## 适应人群

- 使用 Vue 3 或 Nuxt 3 构建中后台、电商、SaaS 等需要跨页面共享状态的前端工程师。
- 维护 Vuex 2/3/4 遗留代码库、计划迁移到官方推荐方案的技术负责人。
- 希望全局状态具备 TypeScript 推导、DevTools 调试与 SSR 友好集成的 Vue 全栈开发者。

## 如何使用

### 前置条件

- 已具备 Vue 3 项目（Vite、Vue CLI 或 `create-vue` 脚手架），或 Nuxt 3 应用。
- Node.js 与 npm、pnpm 或 Yarn 包管理器。
- 浏览器安装 [Vue DevTools](https://devtools.vuejs.org/) 以便调试 Store（可选但推荐）。

### 安装方式

在现有 Vue 3 项目中安装：

```bash
npm install pinia
```

使用 pnpm 或 Yarn 时，将 `npm install` 替换为 `pnpm add pinia` 或 `yarn add pinia`。

**Nuxt 3** 请按[官方 SSR 文档](https://pinia.vuejs.org/ssr/nuxt.html)配置 `@pinia/nuxt` 模块，而非仅手动 `app.use`。

**新建项目** 可在 `npm create vue@latest` 向导中勾选 Pinia，脚手架会生成 `stores/` 目录与示例 Store。

### 首次运行

在应用入口注册 Pinia 插件：

```js
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'

const pinia = createPinia()
const app = createApp(App)

app.use(pinia)
app.mount('#app')
```

创建第一个 Store（建议放在 `src/stores/`）：

```ts
import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  getters: {
    double: (state) => state.count * 2,
  },
  actions: {
    increment() {
      this.count++
    },
  },
})
```

在组件中使用：

```ts
import { useCounterStore } from '@/stores/counter'
import { storeToRefs } from 'pinia'

const store = useCounterStore()
const { count, double } = storeToRefs(store)
```

也可在 [StackBlitz Vue 3 示例](https://stackblitz.com/github/piniajs/example-vue-3-vite) 或 [Nuxt 3 示例](https://stackblitz.com/github/piniajs/example-nuxt-3) 中在线体验，无需本地安装。

### 验证是否成功

- 应用启动无控制台报错，`app.use(pinia)` 后页面正常渲染。
- 在组件中调用 `useCounterStore()` 并执行 `increment()`，界面与 `count` 同步更新。
- 打开 Vue DevTools 的 Pinia 面板，可看到 Store 名称、state 与 action 调用记录。
- TypeScript 项目中，`storeToRefs` 解构的字段应具备正确类型提示。

### 常见坑 / 注意事项

- **Vue 版本**：主分支仅支持 Vue 3；Vue 2 项目请锁定 [v2 分支](https://github.com/vuejs/pinia/tree/v2) 对应版本，勿混用。
- **响应式解构**：直接解构 Store 会丢失响应式，应使用 `storeToRefs()`；actions 可直接从 store 实例解构。
- **SSR / Nuxt**：服务端渲染需按[官方 Nuxt 指南](https://pinia.vuejs.org/ssr/nuxt.html)配置，避免 hydration 不一致；勿在服务端随意访问仅客户端存在的 API。
- **Setup Store 写法**：除 Options 式 `defineStore` 外，还支持 Setup 函数风格（类似 Composition API）；团队应统一一种风格，避免混用增加阅读成本。
- **从 Vuex 迁移**：对照 [Pinia 文档迁移章节](https://pinia.vuejs.org/cookbook/migration-vuex.html) 逐步替换 modules/mutations；大型项目建议按 Store 边界分批迁移而非一次性重写。

---

# Espanso

> 隐私优先的跨平台文本展开器，在任何应用里用触发词自动替换常用片段。

- 页面：https://www.niceshare.site/github/espanso/
- 仓库：https://github.com/espanso/espanso
- 官网：https://espanso.org
- 语言：Rust
- Stars：13972
- 许可证：GPL-3.0
- 标签：开发工具、自动化、CLI
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Espanso 是用 Rust 编写的跨平台文本展开器：当你输入预设触发词（trigger）时，它会在系统级把关键词替换成更长文本、日期、emoji、图片甚至脚本输出。数据 100% 本地处理、无云端追踪，可在 Windows、macOS 与 Linux（含实验性 Wayland）的几乎任意输入框中工作，适合把重复打字变成可版本管理的 YAML 配置。

## 核心特性

- **跨平台系统级展开**：在浏览器、IDE、聊天工具、邮件客户端等任意应用中生效，不依赖单个编辑器插件
- **隐私优先**：配置与展开逻辑完全本地运行，无账号、无遥测，适合处理敏感文案与内部模板
- **Match 规则引擎**：支持多触发词、正则、表单输入、日期变量、Shell 命令与自定义脚本
- **包管理与 Hub**：内置 `espanso install` 从 [Espanso Hub](https://hub.espanso.org/) 安装社区片段包（emoji、代码片段等）
- **应用级配置**：按窗口标题或进程为不同软件加载不同 match/config（如 VS Code 专用代码片段）
- **搜索栏与快捷操作**：`Alt+Space`（macOS 为 `Option+Space`）打开搜索栏快速插入片段；退格可撤销误触发展开

## 对用户价值

重复输入邮件落款、工单回复、API 文档链接或 emoji 组合会拖慢写作与客服节奏。Espanso 把这些内容沉淀为可共享的 YAML 与 Hub 包，一次配置后在所有应用生效，比在每个工具里单独维护 Snippets 更省事。相对云端文本展开 SaaS，它避免把常用话术上传到第三方，也适合离线环境与对 GPL 开源许可有要求的团队。

## 与替代方案

- 相比 **TextExpander / aText** 等商业文本展开器，Espanso 开源免费、全本地、跨三平台；代价是 UI 以文件配置与 CLI 为主，上手曲线更偏极客，且无官方移动端同步。
- 相比 **Alfred / Raycast Snippets**，Espanso 不绑定特定启动器，Windows 与 Linux 同样可用，片段逻辑更完整（正则、表单、脚本）；若你已在 macOS 深度使用 Alfred 且只需简单替换，后者集成更轻。
- 相比 **AutoHotkey**（Windows）或 **Karabiner + 脚本**，Espanso 专注「触发词 → 替换」与可移植 YAML，开箱即用的片段管理更省心；复杂 GUI 自动化或游戏宏仍应选专用工具。
- 若只需 IDE 内代码片段，VS Code / JetBrains 内置 Snippets 足够；Espanso 更适合需要跨应用统一话术的场景。

## 适应人群

- 每天大量回复邮件、工单或 IM，希望用 `:sig`、`:addr` 等触发词统一模板的客服、运营与写作者。
- 需要在 Chrome、Slack、终端与 IDE 之间共享代码片段、命令模板与 emoji 快捷键的开发者。
- 重视数据留在本机、希望用 Git 管理片段配置、并可接受 YAML 编辑的学习型效率用户。

## 如何使用

### 前置条件

- **macOS** 10.13+（Intel / Apple Silicon Universal 包或 Homebrew）
- **Windows** 10+ x64（安装包、便携 zip，或 winget/choco/scoop）
- **Linux**：需先确认桌面环境为 X11 或 Wayland（`echo $XDG_SESSION_TYPE`），再选对应 DEB/RPM/AppImage 包；Wayland 支持仍为实验性质
- 配置文件为 YAML，建议用带缩进的编辑器；可选 [EspansoEdit](https://espanso.org/docs/) 或 VS Code + Red Hat YAML 扩展配合官方 schema

### 安装方式

- **macOS（Homebrew）**：

```bash
brew install espanso
```

若从 0.7.x 旧 tap 升级，可能需要先执行 `brew untap federico-terzi/espanso` 或 `brew untap espanso/espanso`。

- **macOS / Windows**：也可从 [espanso.org/install](https://espanso.org/install) 下载 App 包或安装程序。

- **Windows（winget）**：

```cmd
winget install --id=Espanso.Espanso -e
```

- **Linux**：按发行版与 X11/Wayland 选择 DEB、Terra RPM 或 AppImage，详见 [官方 Linux 安装文档](https://espanso.org/docs/install/linux/)。

### 首次运行

安装后启动 Espanso（macOS/Windows 看菜单栏或任务栏图标；Linux 可执行 `espanso start`）。在任意文本框输入内置触发词 `:espanso`，应展开为 `Hi there!`。编辑默认片段：

```bash
espanso edit
```

或直接修改 `$CONFIG/match/base.yml`（路径可用 `espanso path` 查看）。示例自定义 match：

```yaml
matches:
  - trigger: ":br"
    replace: "Best Regards,\nYour Name"
```

保存后 Espanso 会自动重载配置；也可手动 `espanso restart`。

### 验证是否成功

- 菜单栏/任务栏出现 Espanso 图标，或 `espanso status` 显示正在运行
- 输入 `:espanso` 能正确展开
- 修改 `base.yml` 后新 trigger 生效；`espanso install basic-emojis` 后 emoji 包可用
- `Alt+Space`（macOS：`Option+Space`）能打开搜索栏

### 常见坑 / 注意事项

- **权限与无障碍**：macOS 需在「系统设置 → 隐私与安全性 → 辅助功能」中允许 Espanso；首次打开可能遇到 Gatekeeper 提示，按官方 macOS 安装页操作。
- **Windows SmartScreen**：签名较新的安装包可能弹出警告，需点「更多信息」→「仍要运行」。
- **Linux Wayland**：与 X11 安装包/特性不完全相同，Fedora Wayland 等场景请跟文档选 `espanso-wayland` 或源码编译 feature。
- **YAML 缩进**：match 必须正确缩进，混用 Tab 易导致静默失败；可用 schema 链接校验。
- **许可**：GPL-3.0；若要把内部片段打包进闭源分发物，需自行评估合规。
- **误触发展开**：展开后立即按 `Backspace` 可撤销；可在 `config/default.yml` 设置 `undo_backspace: false` 关闭。

---

# Rolldown

> 用 Rust 编写的 JS/TS 打包器，Rollup 兼容 API，计划作为 Vite 下一代底层引擎，主打极致构建速度。

- 页面：https://www.niceshare.site/github/rolldown/
- 仓库：https://github.com/rolldown/rolldown
- 官网：https://rolldown.rs
- 语言：Rust
- Stars：13784
- 许可证：MIT
- 标签：开发工具、工作流、CLI
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Rolldown 是由 VoidZero 团队用 Rust 编写的 JavaScript/TypeScript 打包器，目标是成为 [Vite](https://vitejs.dev/) 未来的默认底层打包引擎。它在 API 与插件体系上保持与 Rollup 兼容，但在功能范围上更接近 esbuild，并依托 Rust 与 [oxc](https://github.com/oxc-project/oxc) 生态追求更高的构建吞吐。对多数应用而言，官方更推荐通过 Vite 使用 Rolldown，以获得完整的开发服务器、HMR 与生产构建体验。

## 核心特性

- **Rollup 兼容 API**：配置、插件接口与 JavaScript API 与 Rollup 对齐，便于迁移现有 Rollup 插件与构建脚本
- **Rust 高性能核心**：解析、解析依赖与 sourcemap 等底层能力依托 oxc，面向大规模代码库优化构建速度
- **CLI 与配置文件**：支持 `rolldown` 命令行，以及 `.js` / `.ts` 等格式的 `rolldown.config.*`，推荐 `defineConfig` 获得类型提示
- **内置能力与插件生态**：许多场景无需额外插件；同时兼容大部分 Rollup 社区插件，并列出 Vite Plugin Registry 中的社区方案
- **Watch 与多构建配置**：提供与 Rollup 兼容的 `watch` API，并支持在同一配置文件中并行执行多组构建
- **跨平台预编译二进制**：为主流 macOS、Linux、Windows 架构分发原生 binding；冷门平台可回退 Wasm 或从源码构建

## 对用户价值

前端项目在依赖增多后，Rollup 构建往往成为 CI 与本地开发的瓶颈。Rolldown 在保持 Rollup 心智模型的前提下，用 Rust 重写打包热路径，让团队在不推翻现有插件投资的情况下评估更快的构建方案。若你已在用 Vite，关注 Rolldown 等于提前对齐下一代工具链；若你维护库或定制构建流水线，也可单独安装 `rolldown` 做对比基准或渐进迁移。

## 与替代方案

- 相比 [Rollup](https://github.com/rollup/rollup)，Rolldown 强调**构建性能**与 Vite 生态整合，API 兼容但实现与发布节奏独立；复杂 Rollup 插件在边缘场景下仍需实测兼容性。
- 相比 [esbuild](https://github.com/evanw/esbuild)，Rolldown 功能范围更接近「完整打包器」而非仅转译与压缩，并保留 Rollup 式插件与多输出配置，适合需要细粒度打包控制的团队。
- 相比直接选用 [Vite](https://github.com/vitejs/vite) 内置的现有打包后端，单独使用 Rolldown 更适合**库打包、定制 CLI 流水线或性能对比**；完整应用开发仍建议按官方文档通过 Vite 接入。库场景还可关注同生态的 [tsdown](https://tsdown.dev/)。

## 适应人群

- 使用 Vite 或 Rollup，希望提前了解并试验下一代打包引擎的前端工程师。
- 负责 CI 构建耗时优化、需要在 Rollup 插件资产与构建速度之间权衡的基础设施 / 平台同学。
- 维护 npm 库或内部工具链，需要 Rollup 兼容 API 且对 Rust 工具链性能感兴趣的技术负责人。

## 如何使用

### 前置条件

- Node.js 环境，以及 npm、pnpm、yarn 或 bun 等包管理器之一。
- 确认目标平台在[预编译二进制支持列表](https://rolldown.rs/guide/getting-started)内；若为冷门架构，需准备 Wasm 回退或源码编译方案。
- 若计划用于生产应用而非实验，建议对照官方文档确认当前发布渠道（`latest` 1.x 或 `pkg.pr.new` 预览版）的稳定性预期。

### 安装方式

在项目目录安装为开发依赖：

```bash
pnpm add -D rolldown
```

或使用 npm：

```bash
npm install -D rolldown
```

### 首次运行

验证 CLI 是否可用：

```bash
./node_modules/.bin/rolldown --version
```

创建最小示例并打包：

```bash
mkdir -p src
printf "export function hello() { console.log('Hello Rolldown!'); }\n" > src/hello.js
printf "import { hello } from './hello.js';\nhello();\n" > src/main.js
./node_modules/.bin/rolldown src/main.js --file bundle.js
node bundle.js
```

更推荐在 `package.json` 中配置脚本，并使用配置文件：

```javascript
// rolldown.config.js
import { defineConfig } from 'rolldown';

export default defineConfig({
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
  },
});
```

```json
{
  "type": "module",
  "scripts": {
    "build": "rolldown -c"
  }
}
```

### 验证是否成功

- `rolldown --version` 输出版本号且无模块加载错误。
- `pnpm run build`（或等价命令）生成预期产物（如 `bundle.js`），`node bundle.js` 行为符合源码逻辑。
- 若使用 Rollup 插件，在目标配置上跑一遍完整构建并检查输出格式、external 与 sourcemap 是否符合预期。

### 常见坑 / 注意事项

- **平台二进制**：无对应预编译包时 Rolldown 会尝试回退 Wasm；也可设置 `NAPI_RS_FORCE_WASI=error` 强制 Wasm，或在 yarn/pnpm 中配置 `supportedArchitectures` 以安装 Wasm binding。
- **插件兼容性**：虽声明 Rollup 插件 API 兼容，但并非所有社区插件在 Rolldown 上均已验证；迁移前应针对你的配置做回归构建。
- **Watch API 差异**：`watch` 的 `close()` 返回 Promise，与 Rollup 行为略有不同，集成长时间监听流程时需注意异步收尾。
- **库打包场景**：应用开发优先走 Vite；若目标是发布 npm 库，官方文档指向 [tsdown](https://tsdown.dev/) 等专用方案，避免误用 CLI 承担不适合的职责。

---

# QuickJS

> Fabrice Bellard 维护的轻量可嵌入 JavaScript 引擎，极低启动开销，支持 ES2025 与 qjsc 编译为无依赖可执行文件。

- 页面：https://www.niceshare.site/github/quickjs/
- 仓库：https://github.com/bellard/quickjs
- 官网：https://bellard.org/quickjs
- 语言：C
- Stars：10743
- 许可证：MIT
- 标签：开发工具、CLI、后端
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

QuickJS 是由 [Fabrice Bellard](https://bellard.org/) 与 Charlie Gordon 维护的小型 **可嵌入 JavaScript 引擎**，以少量 C 源文件实现、无外部依赖，适合嵌入桌面应用、工具链、脚本宿主或资源受限环境。它提供 `qjs` 命令行解释器与 `qjsc` 编译器，可将脚本编译为**无外部依赖的独立可执行文件**；官方站点 [bellard.org/quickjs](https://bellard.org/quickjs) 提供 tarball、Cosmopolitan 跨平台二进制及预编译工具链（如 TypeScript/Babel）。本 GitHub 仓库为官方源码镜像，详细规范见 `doc/quickjs.html`。

## 核心特性

- **极小体积、易嵌入**：仅数个 C 文件、无第三方依赖；简单 hello world 可执行体在 x86 上约数百 KiB 量级
- **低启动延迟**：完整 runtime 生命周期可低于 300 微秒；单核桌面环境可在约 2 分钟内跑完 ECMAScript Test Suite 相关测试
- **接近完整的 ES2025 支持**：含模块、异步生成器与 Annex B（legacy web 兼容）；选定 ES2025 特性时 test262 通过率接近 100%
- **qjsc 单文件编译**：将 JavaScript 编译为独立二进制，部署时无需附带引擎动态库
- **引用计数 GC + 循环回收**：内存占用可控、行为更可预测，适合嵌入式与确定性场景
- **内置 C API 与标准库**：`std` / `os` 模块及 libregexp、libunicode 等可复用子库，便于在 C/C++ 项目中挂载脚本层

## 对用户价值

若你需要在 C/C++ 应用里嵌入脚本能力，又不想引入 V8/Node 级别的体积与复杂度，QuickJS 以 MIT 许可、单 Makefile 构建和清晰的 C API 降低集成成本。`qjsc` 可把脚本「烤」成独立可执行文件，适合分发 CLI 工具、配置生成器或一次性自动化程序。对追求 ES 标准合规与启动速度的实验性运行时（官方亦提供基于 QuickJS 编译的 TypeScript/Babel 二进制），它是轻量基座；代价是 npm 生态、Node 兼容 API 与 JIT 峰值性能均不如 Node.js/V8，不适合直接替代通用 Web 后端运行时。

## 与替代方案

- 相比 [Node.js](https://nodejs.org/) / [V8](https://v8.dev/)，QuickJS 体积极小、启动极快、嵌入友好；Node/V8 拥有完整 npm 生态、JIT 优化与企业级运维经验，通用服务端与前端构建链仍首选 Node。
- 相比 [QuickJS-NG](https://github.com/quickjs-ng/quickjs)（原项目活跃期的社区 fork），上游 bellard/quickjs 更贴近 Fabrice Bellard 的极简路线与 tarball 发布节奏；NG 侧重 CMake 跨平台、更开放的 PR 流程与持续 ES 特性迭代，若需要 Windows 原生构建或社区驱动发布，可评估 NG。
- 相比 [Duktape](https://duktape.org/) / [JerryScript](https://jerryscript.net/) 等嵌入式引擎，QuickJS 在 ES2025 标准覆盖与 test262 成绩上更激进；Duktape/Jerry 在超小 MCU 场景历史更久，需按目标芯片内存与 ES 版本需求实测选型。
- 边界说明：QuickJS 不是包管理器或 Web 框架；无内置 npm、`node:*` 模块或浏览器 DOM，迁移 Node 脚本需重写 I/O 与依赖层。

## 适应人群

- 在 C/C++ 桌面应用、游戏引擎、网络设备或工具软件中嵌入 JavaScript 脚本层的系统开发者。
- 需要 `qjsc` 将脚本编译为单文件 CLI、或评估 ES2025 合规解释器实现的运行时/语言工具作者。
- 关注 Fabrice Bellard 系极轻量基础软件、愿意从源码或官方 tarball 集成的个人开发者与小团队。

## 如何使用

### 前置条件

- **从源码构建**：Linux 或 macOS 上需 `make` 与 C 编译器（gcc/clang）；Windows 可通过 Linux 主机上的 MinGW 交叉编译（见官方文档）。
- **预编译二进制**：若不想编译，可从 [bellard.org/quickjs 下载页](https://bellard.org/quickjs/) 获取 tarball、Cosmopolitan zip 或各平台 binary release。
- 部分系统若报 atomic 相关链接错误，需在 `Makefile` 的 `LIBS` 增加 `-latomics`，或在 `quickjs.c` 禁用 `CONFIG_ATOMICS`（见官方 Installation 说明）。

### 安装方式

**方式一：官方 tarball（推荐，与发布版本对齐）**

```bash
# 以 2026-06-04 发布为例，版本号请对照 https://bellard.org/quickjs/ 最新页
curl -fsSLO https://bellard.org/quickjs/quickjs-2026-06-04.tar.xz
tar xf quickjs-2026-06-04.tar.xz
cd quickjs-2026-06-04
make
# 可选：sudo make install   # 安装到 /usr/local
```

**方式二：GitHub 源码仓库**

```bash
git clone https://github.com/bellard/quickjs.git
cd quickjs
make
```

构建成功后当前目录生成 `qjs`（解释器）与 `qjsc`（编译器）。

### 首次运行

运行自带示例脚本：

```bash
./qjs examples/hello.js
```

启动交互式 REPL：

```bash
./qjs
```

使用编译器生成无依赖可执行文件：

```bash
./qjsc -o hello examples/hello.js
./hello
```

### 验证是否成功

```bash
./qjs --help          # 应列出命令行选项
./qjs -e "1+2"        # 应输出 3
./qjsc -o /tmp/qjstest examples/hello.js && /tmp/qjstest   # 编译产物可独立运行
```

若执行 `make install`，确认 `/usr/local/bin`（或 Makefile 配置前缀）已在 `PATH` 中，新开终端后 `qjs -e "1+1"` 可得到 `2`。

### 常见坑 / 注意事项

- **与 QuickJS-NG 勿混用 API 假设**：社区 fork 在构建系统、部分 API 与发布节奏上与上游不同，迁移或对比 benchmark 时需标明具体版本与分支。
- **atomic / 架构差异**：ARM 或部分 Linux 发行版可能需调整 `Makefile` 中 `LIBS` 或 `CONFIG_ATOMICS`；交叉编译 Windows 需 MinGW 工具链，非开箱即用。
- **非 Node 运行时**：无 `require('fs')` 等 Node 内置模块语义；I/O 通过 QuickJS `std` / `os` 模块或宿主 C API 提供，勿直接搬运 npm 包。
- **unicode 表重建**：完整重建 unicode 表需额外下载 [quickjs-extras](https://bellard.org/quickjs/) tarball；日常编译官方 release 通常不必自行重建。
- **版本号以 bellard.org 为准**：GitHub 镜像推送节奏与 tarball 发布可能不同步，生产集成建议锁定 tarball 版本号并记录 CHANGELOG。

---

# SQLite

> 全球部署最广的嵌入式 SQL 数据库引擎，单文件零配置，源码以 Fossil 为准、GitHub 为镜像。

- 页面：https://www.niceshare.site/github/sqlite/
- 仓库：https://github.com/sqlite/sqlite
- 官网：https://sqlite.org/
- 语言：C
- Stars：9822
- 许可证：Public Domain
- 标签：开发工具、系统工具、嵌入式
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

SQLite 是部署量最大的 SQL 数据库引擎，以 C 库形式嵌入应用进程，无需独立服务器进程或配置。本 GitHub 仓库为官方 Git 镜像，完整源码可追溯至 2000 年；**权威版本库在 [Fossil](https://sqlite.org/src/timeline)**，Git 中的 commit 名称与官方 check-in 名称不同，沟通与校验完整性时应以 Fossil 官方名称为准。日常集成请优先使用 [sqlite.org 下载页](https://sqlite.org/download.html) 的预编译库与 CLI，而非直接编译镜像仓库。

## 核心特性

- **嵌入式架构**：单文件数据库，零配置启动，适合 App、浏览器、IoT 与边缘节点本地持久化
- **完整 SQL 子集**：事务（ACID）、索引、触发器、视图、CTE 与 JSON 扩展函数
- **跨平台 C 库**：Android、iOS、Windows、Linux 等主流平台均有成熟绑定与 ORM 支持
- **Amalgamation 分发**：`sqlite3.c` 单文件 amalgamation 便于直接嵌入 C/C++ 项目
- **公共领域授权**：源码无版权限制，可自由商用、修改与静态链接，无需开源衍生作品

## 对用户价值

SQLite 把「可靠的关系型存储」压缩到进程内调用，省去数据库运维、网络延迟与连接池复杂度，是移动应用、桌面软件、浏览器（WebAssembly）、测试夹具与单机工具链的默认本地存储。公共领域许可消除了商业合规顾虑；全球生态（Python sqlite3、Node better-sqlite3、Rust rusqlite 等）使集成成本极低。对团队而言，它是 PostgreSQL/MySQL 之外的「本地与嵌入式层」，也是许多 ORM 与框架的内置默认后端。

## 与替代方案

- 相比 **PostgreSQL / MySQL**，SQLite 面向单进程、单文件与嵌入式场景，不支持多客户端网络并发写入；需要多用户服务端数据库时应选客户端/服务器架构。
- 相比 **DuckDB**，SQLite 通用 OLTP 与嵌入式集成更成熟；DuckDB 在单机分析查询与列式 OLAP 负载上通常更优。
- 相比 **LevelDB / RocksDB**，SQLite 提供 SQL 与事务语义；纯 KV、极致写入吞吐或自定义存储引擎场景更适合 LSM 系库。
- 相比 **云托管数据库**，SQLite 无运维成本、离线可用，但需自行处理备份、多实例同步与写入并发扩展。

## 适应人群

- 需要在 App、桌面或嵌入式设备中做本地持久化的移动与全栈开发者。
- 构建 CLI 工具、测试环境或单机 SaaS 时希望零依赖数据库的后端工程师。
- 评估数据层架构、许可合规与「本地优先」存储策略的技术负责人。

## 如何使用

### 前置条件

- 生产与日常开发优先通过 [官方下载页](https://sqlite.org/download.html) 获取预编译 `sqlite3` CLI 与 amalgamation，而非依赖 GitHub 镜像编译。
- 从源码构建需 GCC、GNU make；运行完整测试套件还需 TCL 8.6+ 与 `tcl-dev`（见 `doc/compile-for-unix.md`）。
- 获取最新源码的推荐方式是 [Fossil](https://fossil-scm.org/)：`fossil open https://sqlite.org/src`。

### 安装方式

**macOS / Linux（CLI，推荐快速体验）**

```bash
# macOS
brew install sqlite

# Debian / Ubuntu
sudo apt update && sudo apt install sqlite3 libsqlite3-dev
```

**从 tarball 源码编译（Unix）**

```bash
apt install gcc make tcl-dev   # Debian/Ubuntu 示例
tar xzf sqlite.tar.gz && mkdir bld && cd bld
../sqlite/configure
make sqlite3                   # 命令行工具
make sqlite3.c                 # amalgamation 单文件
```

**Fossil 获取官方源码树**

```bash
mkdir -p ~/sqlite && cd ~/sqlite
fossil open https://sqlite.org/src
fossil update release          # 最新正式发布
```

### 首次运行

使用 CLI 创建并打开本地数据库文件：

```bash
sqlite3 myapp.db
```

在交互式 shell 中执行：

```sql
CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL);
INSERT INTO users (name) VALUES ('alice');
SELECT * FROM users;
```

应用内集成时，链接 `libsqlite3` 或使用各语言官方/社区绑定即可。

### 验证是否成功

```bash
sqlite3 :memory: "SELECT sqlite_version();"
sqlite3 myapp.db "SELECT count(*) FROM users;"
```

能返回版本号并读写表即表示核心功能正常。

### 常见坑 / 注意事项

- **GitHub 仅为镜像**：不接受 Pull Request；问题与补丁请走 [SQLite Forum](https://sqlite.org/forum/) 或 [bugs 论坛](https://sqlite.org/bugs)，安全相关问题可私信维护者。
- **并发写入限制**：同一时刻仅一个写事务；高并发写场景需应用层队列、WAL 模式或迁移到服务端数据库。
- **Git 与 Fossil 名称不一致**：引用 check-in、校验源码完整性时使用 Fossil 官方名称（见 README「Verifying Code Authenticity」）。
- **备份与迁移**：数据库即单文件，复制 `.db` 即可备份；在线备份可用 `.backup` 命令，大版本升级前阅读 [Release Notes](https://sqlite.org/changes.html)。

---

# Kimi CLI

> 月之暗面出品的终端 AI Agent，可读写代码、执行命令，并接入 IDE 与 MCP。

- 页面：https://www.niceshare.site/github/kimi-cli/
- 仓库：https://github.com/MoonshotAI/kimi-cli
- 官网：https://moonshotai.github.io/kimi-cli/
- 语言：Python
- Stars：9767
- 许可证：Apache-2.0
- 标签：AI 编程、Agent、CLI
- 收录：2026-07-19（更新于 2026-07-19）

## 项目介绍

Kimi CLI（现称 Kimi Code CLI）是 Moonshot AI 推出的终端 AI Agent，面向软件开发与日常终端操作。它能阅读和编辑代码、执行 Shell 命令、搜索与抓取网页，并在任务执行中自主规划与调整。官方正将其演进为 [Kimi Code](https://github.com/MoonshotAI/kimi-code)；新用户可直接安装新版，配置与会话会自动迁移。

## 核心特性

- **Shell 命令模式**：`Ctrl-X` 切换，在 Agent 会话中直接跑命令，不必反复进出终端
- **多入口形态**：交互式 `kimi`、本地浏览器 `kimi web`，以及 `kimi acp` 对接 ACP 兼容 IDE
- **MCP 工具链**：`kimi mcp` 管理 HTTP / stdio / OAuth 服务，也可用 `--mcp-config-file` 临时接入
- **编辑器集成**：官方 VS Code 扩展，以及 Zed / JetBrains 等通过 ACP 的 Agent 面板接入
- **Zsh 插件**：配合 [zsh-kimi-cli](https://github.com/MoonshotAI/zsh-kimi-cli)，在 Shell 里一键进入 Agent 模式

## 对用户价值

把「读代码 → 改文件 → 跑命令 → 查资料」收进同一条终端工作流，减少在 IDE、浏览器聊天与 Shell 之间来回切换。对已使用 Kimi 生态、或希望用 ACP / MCP 把 Agent 嵌进现有编辑器的人，上手成本相对低；Apache-2.0 许可也便于在团队内评估与二次集成。

## 与替代方案

- 相比 **Claude Code / Codex**：Kimi CLI 深度绑定月之暗面模型与 OAuth 登录体验；后者分别偏向 Anthropic / OpenAI 生态。
- 相比 **OpenCode / Aider**：OpenCode 更强调多模型切换与开源自由度；Aider 更轻、偏 Git diff 结对。Kimi CLI 的差异在 Shell 模式、ACP 与官方 VS Code / Zsh 配套。
- 若你主要需要 IDE 内补全而非自主 Agent，Continue / Copilot 可能更轻量。
- **迁移边界**：仓库正在向 Kimi Code CLI 收敛；新项目建议优先看 [kimi-code](https://github.com/MoonshotAI/kimi-code) 与最新安装脚本。

## 适应人群

- 习惯终端，想用自然语言驱动改代码、跑构建与探索陌生仓库的开发者。
- 需要把 Agent 接到 VS Code、Zed、JetBrains，或扩展 MCP 工具的人。
- 已在用 Kimi，希望把网页端能力迁到本地 CLI / IDE 工作流的团队。

## 如何使用

### 前置条件

- 支持的操作系统：Linux / macOS / Windows。
- Python 3.12–3.14（官方建议 3.13）；安装脚本可自动安装 `uv`。
- 可用的 API 来源：推荐 Kimi Code OAuth，或自行配置其他平台 API Key。

### 安装方式

官方安装脚本（推荐）：

```bash
# Linux / macOS
curl -LsSf https://code.kimi.com/install.sh | bash
```

```powershell
# Windows (PowerShell)
Invoke-RestMethod https://code.kimi.com/install.ps1 | Invoke-Expression
```

若已安装 `uv`：

```bash
uv tool install --python 3.13 kimi-cli
```

升级 / 卸载：

```bash
uv tool upgrade kimi-cli --no-cache
uv tool uninstall kimi-cli
```

> 新用户也可直接按官方指引安装 Kimi Code；安装后会自动迁移本仓库的配置与会话。

### 首次运行

```bash
cd your-project
kimi
```

首次启动后输入 `/login`，选择平台（推荐 Kimi Code 走浏览器 OAuth）。可用自然语言下任务，例如「帮我看一下这个项目的目录结构」。无 `AGENTS.md` 时可执行 `/init` 生成项目上下文；`/help` 查看斜杠命令。

### 验证是否成功

```bash
kimi --version
```

进入项目后能完成 `/login`，并对仓库提出一个小问题或小改动且得到合理响应，即说明安装与鉴权正常。

### 常见坑 / 注意事项

- **项目演进**：本仓库正逐步收口到 Kimi Code CLI；长期依赖请关注新仓库与文档迁移说明。
- **macOS 首次启动慢**：可在「系统设置 → 隐私与安全性 → 开发者工具」中加入终端应用以加速后续启动。
- **Shell 模式限制**：内置命令如 `cd` 尚不支持；复杂目录切换仍建议在普通 Shell 中完成。
- **ACP 使用前**：需先在终端完成 `/login`，再让 IDE 以 `kimi acp` 启动 Agent 服务。

---

# EverOS

> 本地优先的 Python Agent 记忆运行时：Markdown 真相源 + SQLite/LanceDB，跨应用可移植、用户自持。

- 页面：https://www.niceshare.site/github/everos/
- 仓库：https://github.com/EverMind-AI/EverOS
- 官网：https://evermind.ai/everos
- 语言：Python
- Stars：9553
- 许可证：Apache-2.0
- 标签：Agent、知识管理、本地模型
- 收录：2026-06-28（更新于 2026-06-28）

## 项目介绍

EverOS 是 [EverMind](https://evermind.ai) 开源的 **本地优先 Agent 记忆运行时**：以可读、可 diff、可 Git 版本化的 Markdown 作为真相源，在本地用 SQLite 与 LanceDB 建立检索索引，为编程助手、应用、设备与工作流提供**同一套可移植记忆层**。它区分用户侧 `episodes/profile` 与 Agent 侧 `cases/skills` 两条轨道，支持按 `user_id`、`agent_id`、`app_id`、`project_id`、`session_id` 正交检索，并具备离线 Reflection 在会话间合并记忆簇、精炼画像与技能。

## 核心特性

- **Markdown 真相源**：对话、文件与 Agent 轨迹落盘为 `.md`，可直接编辑；文件变更经 cascade watcher 同步回索引，无需依赖专有仪表盘或黑盒数据库
- **本地三段栈**：Markdown + SQLite + LanceDB，无需 MongoDB、Elasticsearch 或 Redis 等外部服务即可跑通核心记忆循环
- **双轨记忆模型**：用户记忆（episodes/profile）与 Agent 记忆（cases/skills）分离，检索维度正交，便于多应用、多项目、多会话共用同一运行时
- **Knowledge Wiki**：可编辑、带来源引用的 Markdown 知识页，带分类法、CRUD API 与主题检索，与底层记忆文件打通
- **Reflection 自进化**：会话间的离线记忆演化，合并 episode 簇并精炼 profile 与 skills，而非仅做检索型「聊天历史堆叠」
- **OpenAI 协议兼容**：LLM / Embedding / Rerank 可指向 OpenRouter、vLLM、Ollama、DeepInfra 等，通过 `.env` 切换 `*__BASE_URL`
- **Demo 与 Live 模式**：`everos demo` 无需 API Key 即可体验记忆生命周期可视化；`everos demo --live` 连接真实服务端完成写入与召回

## 对用户价值

多数 Agent 记忆方案把状态锁在向量库、图谱或 SaaS 仪表盘里，难以审计、迁移或手工修正。EverOS 把**可读 Markdown + 本地索引**作为默认路径：你能打开 `~/.everos` 直接查看记忆文件，也能在 Claude Code、Codex、OpenCode 等不同工具间复用同一记忆层，避免「每个助手各记各的」。对个人开发者，`everos demo` 零配置即可理解 ingest → extract → index → recall 闭环；对团队，Apache-2.0 许可与自托管服务端降低数据出境与供应商锁定顾虑。

## 与替代方案

- 相比 [Mem0](https://github.com/mem0ai/mem0) 等**API/向量中心型**记忆框架，EverOS 强调 **Markdown 真相源与直接文件编辑**，本地栈仅需 SQLite + LanceDB；若你需要托管多租户记忆池或快速云集成，Mem0 更轻接入，但审计与数据自持成本更高。
- 相比 [Zep](https://www.getzep.com/) 等**商业记忆平台**，EverOS 是**可自托管的开源运行时**，记忆文件落在本地目录、可用 Git 管理；若你接受 SaaS 运维与按量计费，托管方案省去服务端部署。
- 相比仅用 **LangChain Memory / 自建向量检索** 拼装的方案，EverOS 提供**用户/Agent 双轨、Wiki、Reflection 与完整 REST API**（`/api/v1/memory/*`），减少从零设计记忆 schema 与离线巩固逻辑的工作量；若你只需要极简 RAG 片段，轻量向量库可能够用。
- 相比把聊天记录留在**各 IDE 插件内部**，EverOS 定位为**跨应用便携层**；它不替代具体编码 Agent，而是作为可被 MCP、Hive Orchestrator 等集成的统一记忆后端。

## 适应人群

- 在 **Claude Code、Codex、Gemini CLI、OpenCode** 等多工具间切换，希望记忆不随应用丢失的 Agent 开发者。
- 需要**可审计、可手工编辑、可 Git 版本化**记忆文件，而非黑盒向量状态的数据敏感用户或小团队。
- 正在构建带**长期画像、技能沉淀与跨会话召回**的 Agent 产品，且倾向本地优先部署的工程师。
- 希望用 **OpenAI 兼容端点**（OpenRouter、Ollama、vLLM 等）灵活切换模型，同时保持记忆层稳定的自建方案评估者。

## 如何使用

### 前置条件

- **Python 3.12+**；推荐用 [uv](https://github.com/astral-sh/uv) 管理依赖。
- `everos demo`（教育向 TUI 可视化）**无需 API Key**。
- 运行真实服务端记忆流前，需准备 LLM/多模态与 Embedding/Rerank 的 API Key；默认模板使用 [OpenRouter](https://openrouter.ai/)（`EVEROS_LLM__API_KEY`、`EVEROS_MULTIMODAL__API_KEY`）与 [DeepInfra](https://deepinfra.com/)（`EVEROS_EMBEDDING__API_KEY`、`EVEROS_RERANK__API_KEY`），也可改 `.env` 中 `*__BASE_URL` 指向其他 OpenAI 兼容提供商。
- 若需摄取 Office 文档（`.doc`/`.ppt`/`.xls` 等），宿主机须安装 **LibreOffice**（`soffice`）；PDF/图片/音频不受影响。

### 安装方式

```bash
uv pip install everos
# 或: pip install everos
```

可选多模态扩展：

```bash
uv pip install 'everos[multimodal]'
```

从源码贡献/开发：

```bash
git clone https://github.com/EverMind-AI/EverOS.git
cd EverOS
uv sync
source .venv/bin/activate
```

### 首次运行

**1. 先体验 Demo（无需 Key）**

```bash
everos demo
# 非交互环境: everos demo --plain
# 循环展示: everos demo --cinematic
```

**2. 生成配置并填入 API Key**

```bash
everos init
# 或从源码: cp .env.example .env
# XDG 路径: everos init --xdg
```

**3. 启动服务端**

```bash
everos server start
```

**4. 连接真实记忆的 Live Demo**

```bash
everos demo --live
# 非默认地址: everos demo --live --server-url http://127.0.0.1:8000
```

**5. 写入并召回第一条记忆（第二终端）**

```bash
TS=$(($(date +%s)*1000))

curl -X POST http://127.0.0.1:8000/api/v1/memory/add \
  -H 'Content-Type: application/json' \
  -d "{
    \"session_id\": \"demo-001\",
    \"app_id\": \"default\",
    \"project_id\": \"default\",
    \"messages\": [
      {\"sender_id\": \"alice\", \"role\": \"user\", \"timestamp\": $TS, \"content\": \"I love climbing in Yosemite every spring.\"},
      {\"sender_id\": \"alice\", \"role\": \"user\", \"timestamp\": $((TS+10000)), \"content\": \"My favorite coffee shop is Blue Bottle in SOMA.\"}
    ]
  }"

curl -X POST http://127.0.0.1:8000/api/v1/memory/flush \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"demo-001","app_id":"default","project_id":"default"}'

curl -X POST http://127.0.0.1:8000/api/v1/memory/search \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "alice",
    "app_id": "default",
    "project_id": "default",
    "query": "Where do I like to climb?",
    "top_k": 5
  }'
```

### 验证是否成功

- `curl http://127.0.0.1:8000/health` 返回 `{"status":"ok"}`。
- 搜索响应中出现 Yosemite 相关记忆；若首次为空，稍等索引后台同步后重试。
- 打开 `~/.everos`（或你配置的 XDG 路径）可看到生成的 Markdown 记忆文件。
- 贡献者可在仓库内执行 `make test` 通过测试。

### 常见坑 / 注意事项

- `everos demo` 默认是**本地教学可视化**，不连服务端；要验证真实写入/召回请用 `everos demo --live` 或上述 curl 流程。
- `everos server start` 按顺序查找 `.env`：`--env-file` → `./.env` → `${XDG_CONFIG_HOME}/everos/.env` → `~/.everos/.env`；Key 放错路径会导致服务启动但调用失败。
- Markdown 写入同步完成，**LanceDB 索引可能略滞后**于首次搜索，空结果时等待片刻重试。
- Office 文档解析依赖 LibreOffice；未安装时上传返回 HTTP 415，与 PDF/图片解析无关。
- 生产环境请单独管理 API Key，勿将 `.env` 提交进仓库；升级前阅读 [Releases](https://github.com/EverMind-AI/EverOS/releases) 与 [文档](https://docs.evermind.ai)。

---

# 深入理解 AI Agent

> 李博杰著开源 AI Agent 教材：全书正文/PDF 与十章配套实验代码，覆盖上下文、工具、评估与多 Agent。

- 页面：https://www.niceshare.site/github/ai-agent-book/
- 仓库：https://github.com/bojieli/ai-agent-book
- 语言：Python
- Stars：9354
- 许可证：Apache-2.0
- 标签：Agent、AI 编程、工作流
- 收录：2026-07-20（更新于 2026-07-20）

## 项目介绍

**深入理解 AI Agent** 是李博杰所著同名教材的开源主仓库，围绕核心公式 **Agent = LLM + 上下文 + 工具**，提供中文正文/PDF、社区多语言译本，以及与十章一一对应的配套实验代码。内容从基础范式、上下文工程、记忆与 RAG、MCP 工具与 Coding Agent，一路延伸到评估、后训练、自我进化、多模态与多 Agent 协作，适合把理论读透后再亲手跑通。

## 核心特性

- **全书开源**：`book/` 提供引言至第十章 Markdown 正文与编译版中文 PDF；英文/泰米尔语/越南语译本由社区贡献，可直接阅读或自行 `build_pdf.sh` 编译
- **核心公式贯穿**：以 Agent = 模型 + 上下文 + 工具 组织十章，强调 Harness 工程（模型之外的工程能力）才是竞争力所在
- **按章配套代码**：目录为 `chapterN/项目名/`；多数实验可独立运行并已对接真实 LLM API，另有复现指南与设计文档两类标注清晰
- **覆盖主流工程议题**：上下文与 KV Cache、Agent Skills、MCP、Coding Agent、评测基准、SFT/RL、Computer Use、多 Agent 编排等均有可对照实验
- **国内友好的 API 选型**：推荐 Kimi、智谱、Siliconflow、火山引擎、OpenRouter 等，降低从零配模型的摩擦

## 对用户价值

散落的博客、论文与 demo 很难拼出「设计原理 + 可复现实验」的完整学习路径。本仓库把教材正文与按章代码绑在一起：你可以先读 PDF/Markdown 建立框架，再从第 1–2 章可独立运行的项目上手（如 `web-search-agent`、上下文消融），逐步进入记忆/RAG、工具与 Coding Agent；需要评测或训练时，再按附录克隆外部基准与框架。对个人是系统课程，对团队是可共享的 onboarding 与实验模板。

## 与替代方案

- 相比 [LangChain](https://github.com/langchain-ai/langchain) / [Dify](https://github.com/langgenius/dify) 等**框架或平台**，本仓库是**教材 + 按章实验**，目标是理解原理与亲手复现，而非开箱搭业务 Agent。
- 相比 [Claude Code Best Practice](https://github.com/shanraisshan/claude-code-best-practice) 等**单一产品实践索引**，本书覆盖更广的 Agent 系统设计面（上下文、记忆、工具、评估、后训练、多模态、多 Agent），不以某一 CLI 为中心。
- 相比纯论文合集或视频课，这里提供**可运行 Python 实验与消融对照**；但第 6/7/9 章部分评测与训练依赖外部仓库，体积与环境成本高于「只读 PDF」。
- 不替代生产级 Agent 运行时或托管平台；读完应回到具体栈（自研 Harness、Claude Code、开源框架等）落地。

## 适应人群

- 希望系统建立 Agent 心智模型，并从简单 ReAct/搜索 Agent 循序进阶的工程师与研究生。
- 需要上下文工程、RAG/记忆、MCP、Coding Agent 或评测选型对照实验的 AI 应用开发者。
- 带团队做 Agent onboarding，想要一份可 fork、可改、可跑的中文教材与代码基线的 Tech Lead。

## 如何使用

### 前置条件

- Git、Python 3，以及按各子项目 `requirements.txt` 安装依赖的能力。
- 至少申请一个 LLM API Key（推荐 Kimi / 智谱 / Siliconflow / 火山引擎 / OpenRouter；选型参考作者文：[LLM API Setup](https://01.me/2025/07/llm-api-setup/)）。
- 建议先通读 `book/` 对应章节，再跑该章代码；高级章可能还需 GPU 或额外克隆外部仓库。

### 安装方式

克隆主仓库：

```bash
git clone https://github.com/bojieli/ai-agent-book.git
cd ai-agent-book
```

以第 1 章可独立运行的搜索 Agent 为例：

```bash
cd chapter1/web-search-agent
pip install -r requirements.txt
```

仅阅读电子书时，直接打开 [`book/深入理解-AI-Agent-李博杰-v1.2.pdf`](https://github.com/bojieli/ai-agent-book/blob/main/book/深入理解-AI-Agent-李博杰-v1.2.pdf)；若需自行编译 PDF，安装 pandoc、xelatex、ElegantBook 后执行 `cd book && bash build_pdf.sh`。

### 首次运行

配置 API Key（以 Kimi / Moonshot 为例）：

```bash
export MOONSHOT_API_KEY='your-api-key-here'
# 亦支持 KIMI_API_KEY；或写入 .env
```

无 Key 可先看离线演示轨迹：

```bash
python main.py --provider offline-demo
```

有 Key 后跑单次问答或交互模式：

```bash
python main.py "2024年诺贝尔物理学奖获得者是谁？"
# 或：python main.py
```

### 验证是否成功

- 离线模式应打印完整「想 → 做 → 看」ReAct 示例轨迹。
- 在线模式应看到多步工具调用与最终总结；可用 `--output result.json` 落盘轨迹做核对。
- 阅读路径：确认能打开 `book/` 下 PDF 或 `chapter1.md`～`chapter10.md`。

### 常见坑 / 注意事项

- 项目分三类：✅ 可独立运行、📖 复现指南（需另 clone 外部仓）、🚧 设计文档；克隆后先看各目录 README 标注，避免以为「全仓库开箱即跑」。
- 第 6/7/9/10 章部分实验依赖评测基准、训练框架等，完整命令见仓库文末《附录 · 外部仓库获取》；请 `checkout` 到文档指定 commit 以保证复现。
- OpenRouter 等兜底通道可能**没有**厂商专有工具（如 Kimi 内置 `$web_search`）；要真实联网搜索请用对应平台主 Key。
- 子项目许可证可能与根目录 Apache-2.0 不同，商用前核对各目录说明。
- 社区译本可能滞后于中文原版；以 `book/` 中文正文为准。

---

# jcode

> Rust 终端 Coding Agent 框架，极致轻量多会话，内置记忆、Swarm 与广泛模型接入。

- 页面：https://www.niceshare.site/github/jcode/
- 仓库：https://github.com/1jehuang/jcode
- 官网：https://jcode.sh
- 语言：Rust
- Stars：8739
- 许可证：MIT
- 标签：AI 编程、Agent、CLI
- 收录：2026-07-19（更新于 2026-07-19）

## 项目介绍

jcode 是用 Rust 打造的下一代终端 Coding Agent 框架（harness），定位不是「又一个聊天壳」，而是尽可能从同一模型里榨出更多可用工作：多会话并行、Agent 记忆、Swarm 协作与极致资源占用。官方强调 harness 层才是能力跃迁的关键，同时仍可当作日常通用开发工具使用，MIT 开源，官网为 [jcode.sh](https://jcode.sh)。

## 核心特性

- **极致性能与内存**：官方对比显示首帧约 14ms、可输入约 49ms；多会话增量内存约 ~10MB/会话，显著低于 Claude Code、OpenCode、Cursor Agent 等同类终端 Agent
- **Agent 记忆**：对话向量化检索 + 旁路记忆 Agent 提取/校验，被动召回相关记忆，并提供主动 memory 工具与会话 RAG
- **Swarm 多 Agent**：同一仓库可拉起多个会话，服务端协调文件冲突通知与私信/广播；Agent 也可自行 spawn 工作组并行干活
- **广泛模型接入**：Claude / OpenAI / Gemini / Copilot / Azure / Ollama / LM Studio 等 OAuth 或配置登录，以及大量 OpenAI-compatible 配置档与自建端点
- **可定制与可迁移**：Self-dev 模式可让 Agent 改自身源码并热重载；支持从 Claude Code、Codex、OpenCode、pi 等会话 resume；内置 Firefox 浏览器自动化与 MCP（兼容 Claude Code 配置导入）

## 对用户价值

当你真正需要「同时开很多会话」或「让多个 Agent 在同一仓库协作」时，多数终端 Agent 的内存与启动成本会迅速爆炸；jcode 把 harness 做成可扩展的基础设施，让多会话成为默认能力而不是负担。语义记忆减少反复喂上下文的 token 浪费，confidence stepping / auto-poke / hill-climbable goals 等机制则针对「过早收工、空转声明完成」这类常见失败模式。对已在用 Claude Code 或 Codex 的用户，还可在会话中断后用 jcode 续跑，降低迁移切换成本。

## 与替代方案

- 相比 **Claude Code**，jcode 开源、模型可换、多会话内存更省，并强调 Swarm/记忆等 harness 能力；Claude Code 在 Anthropic 官方产品体验与生态集成上更成熟。
- 相比 **OpenCode**，两者都是开源终端 Agent；jcode 以 Rust 与资源效率见长，OpenCode 在多入口形态（TUI/桌面/IDE）与模型目录生态上更广。
- 相比 **Codex CLI**，jcode 提供更重的多会话协调、记忆与 Swarm；Codex 更贴近 OpenAI 官方链路与订阅体验。
- 若只需要 IDE 内补全或轻量结对，**Continue** / **Aider** 可能更简单；jcode 适合把终端 Agent 当作主力工作流。

## 适应人群

- 习惯终端 TUI、希望并行多会话或 Swarm 协作的 AI 编程用户。
- 对启动延迟与内存占用敏感、需要在同一机器跑大量 Agent 的个人或小团队。
- 已有 Claude Code / Codex / OpenCode 会话、想换 harness 续跑或接入本地/自建模型的迁移用户。

## 如何使用

### 前置条件

- **Linux**（x86_64 / aarch64）、**macOS**（Apple Silicon / Intel）或 **Windows 11**（原生或 WSL2）；Termux 需先 `pkg install glibc patchelf`
- 至少一个可用模型通路：订阅 OAuth（Claude / OpenAI / Gemini / Copilot 等）、API Key，或本地 Ollama / LM Studio / vLLM 等 OpenAI-compatible 端点
- 现代终端模拟器；需要浏览器自动化时准备 Firefox（通过内置 Firefox Agent Bridge）

### 安装方式

**推荐（macOS / Linux）：**

```bash
curl -fsSL https://jcode.sh/install | bash
```

**Homebrew：**

```bash
brew tap 1jehuang/jcode
brew install jcode
```

**Windows（PowerShell 5.1+）：**

```powershell
irm https://jcode.sh/install.ps1 | iex
```

**源码构建：**

```bash
git clone https://github.com/1jehuang/jcode.git
cd jcode
cargo build --release
scripts/install_release.sh
```

### 首次运行

```bash
# 登录提供商（按需选择其一）
jcode login --provider claude
# 或：openai / gemini / copilot / ollama / lmstudio / openai-compatible ...

# 启动交互式 TUI
jcode

# 非交互冒烟
jcode run "say hello"
```

本地模型示例：先启动 Ollama 并拉取模型，再 `jcode login --provider ollama`，用 `jcode --provider ollama --model llama3.2 run 'hello'` 验证。无头/SSH 环境可用 `jcode login --provider <provider> --no-browser`。

### 验证是否成功

- `jcode` 在 PATH 中可启动，TUI 正常渲染输入
- `jcode auth-test --all-configured` 或 `jcode run "say hello"` 能拿到模型回复
- 可选：`jcode browser status` / `jcode browser setup` 确认浏览器工具可用；多会话可试 `jcode serve` 后再 `jcode connect`

### 常见坑 / 注意事项

- 官方性能数字来自特定机器与版本对照，换硬件/模型后观感会变；本地 embedding 关闭时内存会更低，但记忆能力受影响
- Self-dev 会改 jcode 自身源码并重载二进制，建议用前沿模型，弱模型可能引入隐蔽破坏
- MCP 目前主要支持 stdio 型服务器；HTTP/SSE 条目会被识别并跳过
- Windows 安装、Defender / SmartScreen 与可选组件说明见仓库 `docs/WINDOWS.md`；卸载默认保留配置与会话，完整清理需 `--purge`
- 项目迭代快（README 含大量实验性 harness 能力），升级前建议看 Releases，并在隔离目录先试用

---

# Starlight

> 基于 Astro 的文档站主题，内置导航、搜索、i18n、SEO 与暗色模式，开箱即用的高性能技术文档方案。

- 页面：https://www.niceshare.site/github/starlight/
- 仓库：https://github.com/withastro/starlight
- 官网：https://starlight.astro.build/
- 语言：TypeScript
- Stars：8693
- 许可证：MIT
- 标签：开发工具、知识管理、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Starlight 是 [Astro](https://astro.build/) 官方维护的文档站主题与集成（`@astrojs/starlight`），面向需要快速上线、又希望长期可维护的技术文档场景。它在 Astro 的内容层（Content Collections）之上提供导航侧栏、站内搜索、国际化、SEO、可读排版、代码高亮、暗色模式等完整能力，并自带卡片、标签页等文档组件。Starlight 自身文档站即由 Starlight 构建，可作为功能与体验的参考样板。

## 核心特性

- **开箱即用的文档体验**：站点导航、搜索、i18n、SEO、排版、代码高亮与暗色模式等常见文档需求默认集成，减少从零拼装主题的时间
- **基于 Astro 内容层**：通过 `docsLoader` 与 `docsSchema` 管理 `src/content/docs/` 下的 Markdown、MDX 与 Markdoc，frontmatter 具备 TypeScript 类型校验
- **多标记语言与文件路由**：内容文件即页面路由，支持在文档中混用 Astro 生态的 UI 组件（React、Vue、Svelte、Solid 等）
- **可扩展的插件与主题**：官方维护 [Plugins](https://starlight.astro.build/resources/plugins/) 与 [Themes](https://starlight.astro.build/resources/themes/) 目录，社区可扩展搜索、分析、组件等行为
- **新建与增量接入**：可用 `create astro` 模板一键脚手架，也可在现有 Astro 项目中通过 `astro add starlight` 增量集成

## 对用户价值

自建文档站时，团队往往在主题、搜索、导航与部署之间反复权衡，Docusaurus 或 VitePress 等方案又绑定特定前端栈。Starlight 把「文档站该有的默认体验」打包成 Astro 集成：若你已在用 Astro 做产品站，可在同仓追加文档分区；若从零开始，模板几分钟即可本地预览。Astro 的静态优先与按需水合模型，也让多数文档页在性能与可访问性上具备良好基线，适合开源 README 升级、API 参考与内部手册等长期维护的内容站点。

## 与替代方案

- 相比 [Docusaurus](https://docusaurus.io/)（React 生态），Starlight 更轻量地依托 Astro，不强制 React 作为主 UI 栈，适合已熟悉 Astro 或希望文档与营销站共用工具链的团队。
- 相比 [VitePress](https://vitepress.dev/)（Vue 生态），两者都强调 Markdown 优先与快速启动；Starlight 在 i18n、内置组件与 Astro 集成生态上更完整，VitePress 则对 Vue 项目内嵌文档更自然。
- 相比 [Nextra](https://nextra.site/)（Next.js）或 [MkDocs Material](https://squidfunk.github.io/mkdocs-material/)（Python），Starlight 面向 Node/前端工作流，并可直接复用 Astro 集成市场；若团队主力栈是 Next 或 Python，对应方案往往迁移成本更低。
- 边界说明：Starlight 专注**文档站**而非通用 CMS 或博客平台；复杂多租户、重度自定义后台或非文档型站点需评估是否引入 Astro 全栈能力。

## 适应人群

- 维护开源库或 SaaS 产品，希望把 README 升级为可搜索、可版本化的正式文档站的开发者。
- 已在用 Astro 构建官网，想以最小成本追加 `/docs` 或子路径文档区的全栈 / 前端团队。
- 技术写作者与 Developer Advocate，需要 Markdown/MDX 写作体验、暗色模式与 i18n，且重视 Lighthouse 类性能指标的团队。

## 如何使用

### 前置条件

- Node.js 18+（与当前 Astro 版本要求保持一致，以[官方文档](https://docs.astro.build/en/install-and-setup/)为准）。
- 包管理器：npm、pnpm 或 Yarn 均可。
- 新建项目无需预先安装 Astro；在现有项目中集成时，需已有可运行的 Astro 工程。

### 安装方式

**方式一：新建 Starlight 项目（推荐）**

```bash
npm create astro@latest -- --template starlight
```

使用 pnpm 时：

```bash
pnpm create astro@latest --template starlight
```

**方式二：在现有 Astro 项目中添加**

```bash
npx astro add starlight
```

随后在 `astro.config.mjs` 中配置 `title`，并在 `src/content.config.ts` 注册 `docs` 集合（见下方首次运行）。

### 首次运行

进入项目目录启动开发服务器：

```bash
npm run dev
```

终端会输出本地预览 URL（默认 `http://localhost:4321`）。在 `src/content/docs/` 下新增 Markdown 文件即可生成页面，例如首页 `index.md`：

```markdown
---
title: My docs
description: Learn more about my project in this docs site built with Starlight.
---

Welcome to my project!
```

若在现有项目中手动集成，需确保 `src/content.config.ts` 包含：

```typescript
import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
};
```

### 验证是否成功

- 浏览器打开 dev server URL，能看到 Starlight 默认布局、侧栏与首页内容。
- 在 `src/content/docs/` 新增页面后，保存文件应触发热更新并在导航中可见。
- 运行 `npm run build` 能成功产出静态站点；`npm run preview` 可本地预览生产构建结果。

### 常见坑 / 注意事项

- **内容目录结构**：默认路由基于 `src/content/docs/` 文件路径；若文档需统一挂在子路径（如 `/guides/`），需将文件放入对应子目录，详见[手册](https://starlight.astro.build/manual-setup/)。
- **SSR 与预渲染**：Starlight 文档页默认预渲染；若项目启用 SSR 并需关闭某页预渲染，需显式设置 `prerender: false`，Cloudflare 等适配器可能还需 `nodejs_compat` 等额外配置。
- **版本升级**：使用 `npx @astrojs/upgrade` 同步升级 Starlight 与 Astro 相关包，升级前阅读 [Starlight changelog](https://github.com/withastro/starlight/blob/main/packages/starlight/CHANGELOG.md) 中的破坏性变更。
- **求助渠道**：问题可先查 [Starlight 文档](https://starlight.astro.build/)与 [Astro 文档](https://docs.astro.build/)；社区支持见 Astro Discord 的 `#support`（带 `starlight` 标签）或 `#starlight` 频道。

---

# AI Berkshire

> 面向 Claude Code / Codex 的价值投资 Skill 合集，四大师对抗式分析 + 18 个投研入口。

- 页面：https://www.niceshare.site/github/ai-berkshire/
- 仓库：https://github.com/xbtlin/ai-berkshire
- 官网：https://github.com/xbtlin/ai-berkshire#readme
- 语言：Python
- Stars：8592
- 许可证：MIT
- 标签：AI 编程、Agent、工作流
- 收录：2026-07-03（更新于 2026-07-03）

## 项目介绍

**AI Berkshire** 是一套同时兼容 **Claude Code** 与 **Codex** 的价值投资研究 Skill 合集。它将巴菲特、芒格、段永平、李录四位大师的方法论系统化，通过多 Agent 并行与结构化流程，把「直接问 AI 得到两面讨好的分析」升级为「可以拿来做决策的投研报告」。仓库提供 18 个按场景划分的 Skill 入口，覆盖深度研究、财报精读、行业筛选、持仓管理与思维工具，并附带 Python 财务校验脚本保证数据精确性。

## 核心特性

- **四大师对抗式分析**：商业模式（段永平）、财务估值（巴菲特）、逆向思考（芒格）、长期确定性（李录）四视角并行，强制输出通过/不通过/灰色地带结论，而非「一方面…另一方面…」
- **18 个 Skill 入口**：`/investment-team` 多 Agent 并行投研、`/earnings-review` 一手财报精读、`/industry-funnel` 行业漏斗筛选、`/portfolio-review` 组合管理等，按场景即插即用
- **结构化反偏见机制**：信息丰富度 A/B/C 评级、芒格式逆向检验、8 条快速否决红线、反共识检查与留白原则，降低 AI「看起来对但经不起推敲」的风险
- **金融数据精确校验**：关键指标用 Python `decimal.Decimal` 计算，至少 2 个独立来源交叉验证；`tools/financial_rigor.py` 可手算校验市值等关键数据
- **可复现的研究流程**：同样输入产出结构一致、深度一致的报告，支持多公司横向对比与同标的定期复评
- **双客户端支持**：同一套 canonical workflow，分别提供 Claude Code commands 与 Codex skills / slash prompts 安装脚本

## 对用户价值

直接问 LLM 做投研，往往得到格式随机、结论模糊、数据可能算错的「平衡分析」。AI Berkshire 解决的是**分析质量与决策纪律**问题：强制分层建议与价格区间、四视角制造真实张力、内置防骗机制，并用 Python 工具兜底数值精度。对个人投资者，它相当于「一个人 + Claude Code = 一个投研团队」；对分析师，它提供可版本化、可复现的研究模板，让团队成员之间的输出可以对齐。

## 与替代方案

- 相比直接向 ChatGPT / Claude 提问，本框架强制**结构化结论、多视角对抗与反偏见机制**，避免「看起来对但无法决策」的泛化分析。
- 相比 [OpenBB](https://github.com/OpenBB-finance/OpenBB) 等**金融数据终端 / SDK**，AI Berkshire 侧重**价值投资方法论 + Agent 工作流**，而非行情数据聚合或量化回测平台。
- 相比通用 [Superpowers](https://github.com/obra/superpowers) 等**研发方法论 Skill 库**，这里 18 个入口全部围绕**基本面投研场景**定制，含财报、行业漏斗、持仓追踪等垂直流程。
- 框架作者公开了实盘业绩截图（2024 +69.29%、2025 +66.38%），但 README 明确**历史收益不代表未来**；投资决策仍需自行承担风险，Skill 输出是辅助而非投资建议。

## 适应人群

- 使用 Claude Code 或 Codex，希望把价值投资方法论落地为可重复 Agent 工作流的个人投资者与分析师。
- 需要深度研究、财报精读、行业筛选或持仓管理结构化流程，而非单次 prompt 的投研用户。
- 关注 AI Agent 并行协作、金融数据精确校验，想从成熟 Skill 库快速部署投研能力的效率型用户。

## 如何使用

### 前置条件

- 已安装 **Claude Code** 或 **Codex** 之一（见下方安装命令）。
- 克隆仓库需 Git 与 Bash 环境；财务校验脚本依赖 Python 3。
- Skills 会频繁调用工具；Claude Code 默认逐次授权，可信环境下可用 `claude --dangerously-skip-permissions` 跳过确认（会关闭工具审批保护，请谨慎使用）。

### 安装方式

**Claude Code 用户：**

```bash
npm install -g @anthropic-ai/claude-code
git clone https://github.com/xbtlin/ai-berkshire.git
cd ai-berkshire
./scripts/install-claude-commands.sh
```

**Codex 用户：**

```bash
# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# 或 npm install -g @openai/codex

git clone https://github.com/xbtlin/ai-berkshire.git
cd ai-berkshire
./scripts/install-codex-skills.sh
# 可选：安装 slash prompts 获得接近 Claude Code 的 /investment-research 体验
./scripts/install-codex-prompts.sh
```

### 首次运行

在 Claude Code 中直接调用 Skill，例如：

```bash
/investment-research 腾讯
/investment-team 美团
/earnings-review 腾讯 2025Q4
/industry-funnel AI算力
```

Codex 用户安装后重启，按 skill 名称描述任务，例如「使用 investment-research 研究腾讯」；若安装了 slash prompts，可用 `/prompts:investment-research 腾讯`。

### 验证是否成功

- Claude Code：`/investment-checklist 茅台, 英伟达, 苹果` 应输出结构化 Checklist 表格。
- Codex：`codex --version` 正常输出版本号，且 `~/.codex/skills` 下可见已安装的 skill 目录。
- 财务工具：`python3 tools/financial_rigor.py --help` 可正常显示子命令。

### 常见坑 / 注意事项

- Claude Code 工具授权频繁打断流程；仅在信任仓库与环境时使用 `--dangerously-skip-permissions`。
- Codex 与 Claude Code 的入口语法不同：Codex 以 skill 名称描述任务，slash prompts 为可选兼容层。
- LLM 心算不可靠，涉及 PE、市值等关键数据务必走 `financial-data` skill 或 `financial_rigor.py` 校验。
- 实盘业绩为作者个人案例，**不构成投资建议**；输出结论需结合独立判断与合规要求。
- 部分 Skill（如 `/deep-company-series`）产出篇幅极长，注意上下文窗口与 API 用量。

---

# SnapDOM

> 高性能 DOM 截图引擎，将页面元素导出为 PNG/SVG/WebP，零依赖且比 html2canvas 更快。

- 页面：https://www.niceshare.site/github/snapdom/
- 仓库：https://github.com/zumerlab/snapdom
- 官网：https://snapdom.dev
- 语言：JavaScript
- Stars：7887
- 许可证：MIT
- 标签：开发工具、前端、Web API
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

SnapDOM 是新一代 DOM 捕获引擎，可将任意 DOM 子树转换为自包含的图像表示，并导出为 SVG、PNG、JPG、WebP、Canvas 或 Blob。它基于标准 Web API 构建，无运行时依赖，在官方基准测试中显著快于 html2canvas 与 html-to-image，适合需要在前端生成分享图、海报或报表截图的场景。

## 核心特性

- 完整捕获 DOM：内联样式、伪元素（`::before`/`::after`）与字体
- 支持 Shadow DOM、同源 iframe、CSS `counter()`/`counters()` 与 `line-clamp`
- 一次克隆、多次导出：可复用捕获结果分别输出 PNG、SVG、JPG、WebP 或触发下载
- 插件体系（Beta）：通过生命周期钩子扩展捕获流程，支持自定义导出格式
- 零依赖、纯 Web API，提供 ESM/CJS 与 CDN 多种引入方式

## 对用户价值

传统方案（html2canvas、dom-to-image）在复杂节点上往往慢且样式还原不稳定。SnapDOM 通过「克隆 → 样式内联 → 图片/字体嵌入 → SVG foreignObject → 导出」的流水线，在保持高还原度的同时把捕获耗时压到毫秒级。对需要「页面内一键保存为图片」的产品（分享卡片、数据看板、设计稿导出）来说，集成成本低、包体小、API 直观。

## 与替代方案

- **html2canvas**：生态成熟、文档多，但复杂 DOM 下性能明显落后；SnapDOM 在官方基准中同类场景快一个数量级以上。
- **html-to-image / dom-to-image**：轻量易用，但对伪元素、字体嵌入与 Shadow DOM 的支持不如 SnapDOM 完整。
- **服务端截图（Puppeteer 等）**：适合整页或跨域场景，但需要后端资源；SnapDOM 适合纯前端、用户当前视口内的元素级导出。
- **局限**：跨域图片需 CORS 或 `useProxy`；Safari 上 WebP 会回退 PNG，嵌入字体时性能受 WebKit 限制；自定义滚动条样式仅在未滚动时生效。

## 适应人群

- 需要在 Web 应用内实现「保存为图片」「生成分享海报」的前端开发者。
- 正在从 html2canvas 迁移、希望提升捕获速度与样式还原度的团队。
- 构建低代码/报表/设计工具，需要可扩展导出管线的工程师。

## 如何使用

### 前置条件

- 现代浏览器环境（Chromium、Firefox、Safari 等；部分特性在 Safari 有已知限制）。
- Node.js 18+（若通过 npm 安装并在构建工具中使用）。
- 待捕获元素内的外部图片需允许跨域访问，否则需配置 `useProxy`。

### 安装方式

```bash
npm i @zumer/snapdom
# 或
yarn add @zumer/snapdom
```

CDN 引入：

```html
<script type="module">
  import { snapdom } from "https://unpkg.com/@zumer/snapdom/dist/snapdom.mjs";
</script>
```

插件（可选）：

```bash
npm install @zumer/snapdom-plugins
```

### 首次运行

一行代码将元素导出为 PNG：

```js
import { snapdom } from '@zumer/snapdom';

const img = await snapdom.toPng(document.querySelector('#card'));
document.body.appendChild(img);
```

可复用捕获、多次导出：

```js
const result = await snapdom(document.querySelector('#card'));
await result.toPng();
await result.download({ format: 'jpg', filename: 'card.jpg' });
```

### 验证是否成功

在目标页面上对已知 DOM 节点调用 `snapdom.toPng()`，检查生成的图片是否包含预期文字、背景图与伪元素样式。可在 [snapdom.dev](https://snapdom.dev) 在线 Demo 对比效果。

### 常见坑 / 注意事项

- 跨域图片未配置 CORS 会导致捕获空白或缺失，可启用 `useProxy` 选项。
- Safari 上使用 WebP 格式会自动回退为 PNG；嵌入字体（`embedFonts`）时捕获较慢，可通过 `safariWarmupAttempts` 调优。
- 通过 JS `FontFace()` 动态加载的字体需参考官方 issue #43 的 workaround。
- 元素已滚动时，自定义 `::-webkit-scrollbar` 样式不会被捕获。
- 生产环境建议锁定稳定版 `@zumer/snapdom`，`@dev` 标签含新特性但可能不够稳定。

---

# FileBrowser Quantum

> 自托管 Web 文件管理器，支持索引搜索、多源挂载与企业级 SSO 与分享权限。

- 页面：https://www.niceshare.site/github/filebrowser/
- 仓库：https://github.com/gtsteffaniak/filebrowser
- 官网：https://filebrowserquantum.com
- 语言：Go
- Stars：7317
- 许可证：Apache-2.0
- 标签：自托管、工作流、开发工具
- 收录：2026-06-28（更新于 2026-06-28）

## 项目介绍

FileBrowser Quantum 是经典 FileBrowser 的大规模 fork，定位为「最好用的免费自托管 Web 文件管理器」。它用单一可执行文件或轻量 Docker 镜像，把本地目录、NAS 挂载点暴露为现代响应式 Web 界面，并叠加 SQLite 索引搜索、细粒度分享与企业登录集成，适合不想上完整网盘套件、又需要多人协作与外链分享的场景。

## 核心特性

- 多数据源配置：支持多路径、include/exclude 规则，统一 `config.yaml` 管理
- SQLite 索引与实时搜索：输入即搜，支持文件/文件夹大小与多种筛选；UI 实时刷新
- 企业级认证：OIDC、LDAP、JWT、密码 + 2FA、反向代理登录
- 目录级权限：按用户或用户组限定可访问路径
- 富媒体预览：Office、视频、专辑封面、3D 模型缩略图；文件夹大小与滚动位置记忆
- 可配置分享：过期时间、匿名/指定用户、主题样式、查看/编辑/上传权限
- 开发者 API：长期 API Token，启用后可在 `/swagger` 查看接口文档
- 跨平台：Linux / Windows / macOS 均有独立二进制；Docker 镜像约 60 MB（含 FFmpeg）

## 对用户价值

远程访问 NAS、服务器备份或开发机上的文件，往往要在 SFTP、VPN 和笨重网盘之间取舍。Quantum 用浏览器即可上传、预览、编辑文本与 Office 文件，并通过索引搜索在大目录里快速定位；配合 SSO 与分享链接，小团队无需部署 Nextcloud 也能完成「私有文件门户」。相比原版，它移除了 shell 命令执行能力，安全性更偏「只读/受控文件访问」而非远程终端。

## 与替代方案

- 相比 [filebrowser/filebrowser](https://github.com/filebrowser/filebrowser) 原版，Quantum 增加索引搜索、OIDC/LDAP、多数据源、Office 预览与 API；镜像略大（约 60 MB vs 31 MB），且不再支持 shell 命令。
- 相比 Filestash，Quantum 专注本地/挂载文件系统，暂无 S3/FTP 连接器；但 SSO、索引搜索与分享定制在对比表中更完整，独立二进制部署更简单。
- 相比 Nextcloud，Quantum 不做协作办公套件，无移动 App；胜在轻量、专注「浏览 + 分享 + 权限」，Homelab 资源占用更低（官方建议最低约 512 MB 内存）。
- 部分能力仍在建设中（标签、回收站、活动日志、文档转换等标注为 :construction:），升级前请查阅 [Releases](https://github.com/gtsteffaniak/filebrowser/releases) 与官方文档。

## 适应人群

- 有 NAS / VPS / Homelab，想通过浏览器管理本地文件并对外分享链接的用户。
- 小团队需要多用户、目录级权限与企业 SSO，但不想维护完整网盘栈的运维者。
- 已从原版 FileBrowser 迁移或评估 fork 差异的 self-host 爱好者（官方提供 [迁移指南](https://filebrowserquantum.com/en/docs/getting-started/migration/)）。

## 如何使用

### 前置条件

- 已安装 Docker Engine 与 Docker Compose 插件，或目标平台的独立二进制运行环境。
- 准备一个待挂载的本地目录（勿将容器内 `/` 或 `/var` 作为源路径）。
- v1.3.x 起 Docker 默认以 `filebrowser` 用户（UID:GID 1000:1000）运行；挂载的 `data` 目录需匹配权限。

### 安装方式

**快速试用**（无持久化，重启后配置丢失）：

```bash
docker run -d \
  -v $(pwd):/srv \
  -p 80:80 \
  gtstef/filebrowser:stable
```

**推荐：Docker Compose 持久化部署**

```bash
mkdir -p filebrowser/data && cd filebrowser
touch ./data/config.yaml
```

编辑 `./data/config.yaml` 示例：

```yaml
server:
  cacheDir: /home/filebrowser/data/tmp
  sources:
    - path: /folder
      config:
        defaultEnabled: true
```

创建 `docker-compose.yaml`：

```yaml
services:
  filebrowser:
    image: gtstef/filebrowser:stable
    volumes:
      - /path/to/your/folder:/folder
      - ./data:/home/filebrowser/data
    ports:
      - 80:80
    restart: unless-stopped
```

```bash
docker compose up -d
```

镜像亦可通过 `ghcr.io/gtsteffaniak/filebrowser` 拉取；`stable-slim`（约 15 MB）不含 FFmpeg/文档预览。完整说明见 [官方 Docker 文档](https://filebrowserquantum.com/en/docs/getting-started/docker/)。

### 首次运行

浏览器访问 `http://localhost`（或你映射的主机端口），默认账号 `admin` / `admin`，登录后**立即修改密码**。在管理界面配置用户、数据源与分享策略；若修改了 `server.port`，需同步调整 Compose 端口映射与健康检查。

### 验证是否成功

- 能登录 Web 界面并浏览挂载目录中的文件。
- 搜索框输入文件名可看到实时索引结果（大目录首次索引可能需要等待）。
- 访问 `http://localhost/health` 返回正常（若启用健康检查）。
- 创建测试分享链接，确认权限与过期策略符合预期。

### 常见坑 / 注意事项

- 配置中的 `sources.path` 是**容器内路径**，须与 `volumes` 挂载一致；勿把宿主机根目录 `/` 直接暴露给服务。
- v1.2.x 及更早版本 Docker 默认 root 用户；v1.3.x 起默认非 root，低权限端口（80/443）在 rootless 环境可能需 `cap_add: [NET_BIND_SERVICE]` 或改用高位端口。
- 数据库默认位于 `/home/filebrowser/data/database.db`（Docker），需将 `./data` 持久化挂载以免重建容器后丢失用户与索引。
- 已移除 shell 命令功能；若依赖原版「在容器内执行命令」工作流，需改用其他方案。
- 官方文档目前主要为英文；生产部署建议配合反向代理配置 HTTPS，参见 [反向代理指南](https://filebrowserquantum.com/en/docs/getting-started/reverse-proxy/)。

---

# Battery

> Apple Silicon Mac 电池充电管理工具，可将长期插电设备的电量维持在 80% 以延长寿命，提供菜单栏 GUI 与 CLI。

- 页面：https://www.niceshare.site/github/battery/
- 仓库：https://github.com/actuallymentor/battery
- 语言：Shell
- Stars：7042
- 许可证：MIT
- 标签：CLI、开发工具、系统工具
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

[Battery](https://github.com/actuallymentor/battery) 是面向 Apple Silicon MacBook（M1/M2/M3 等）的电池充电管理工具，开源 MIT，提供菜单栏 GUI 与 `battery` 命令行。核心思路是：长期接电时把电量维持在约 80%，减少满充与高温对锂电寿命的损耗。作者因 AlDente 许可限制而自建此项目，GUI 基于 Electron，底层通过 SMC 工具读写充电状态，重启或关闭托盘应用后限制仍生效。

## 核心特性

- **80% 充电上限**：插电时电量超过 80% 停止充电，低于 80% 再恢复，并可主动放电至目标区间
- **重启后仍生效**：限制在重启、关闭托盘应用后保持，适合长期接电的桌面办公场景
- **GUI + CLI 双模式**：`brew install battery` 或 DMG 安装菜单栏应用；也可单独用一行脚本安装 CLI
- **可配置维持区间**：CLI 支持 `battery maintain 80` 或 `battery maintain 70-80` 等自定义百分比（仅 CLI 可设非 80% 上限）
- **完整充电控制**：`charging on/off`、`adapter on/off`、充至指定电量、放电至指定电量、校准流程等
- **仅 Apple Silicon**：依赖 SMC，不支持 Intel Mac；Intel 用户可考虑 AlDente 等替代

## 对用户价值

笔记本长期接电却默认充到 100%，会加速电池老化；macOS 自带的「优化电池充电」依赖机器学习与固定作息，作息不规律时效果不稳定。Battery 让你主动设定维持百分比，行为可预期：插电办公时电量稳定在 80% 附近，需要满充时可用 `battery charge 100` 或关闭限制。对习惯终端自动化的用户，CLI 可写入脚本或 cron；对普通用户，菜单栏应用首次输入管理员密码后即可后台运行，无需反复干预。

## 与替代方案

- 相比 **macOS 优化电池充电（Optimized Charging）**：系统功能会预测你的插电规律，在「预计长时间接电」时才延迟充过 80%，且无法精确指定维持百分比；Battery 由用户主动开关，可固定 80% 或自定义区间，适合作息不固定、需要确定性的场景。
- 相比 **[AlDente](https://apphousekitchen.com/)**：AlDente 功能更丰富（Intel 也支持、有付费高级版），但免费版许可对重度用户较严；Battery 完全开源 MIT，CLI 可脚本化，GUI 更轻量。Intel Mac 用户应选 AlDente 而非 Battery。
- 相比 **手动拔电源、靠习惯控电量**：Battery 在插电状态下自动放电/停充，无需物理拔线，且重启后策略仍保留。

## 适应人群

- 长期将 M 系列 MacBook 接电源使用的开发者、设计师与居家办公用户。
- 希望用 CLI 将充电策略写入脚本、dotfiles 或自动化流程的终端用户。
- 觉得系统「优化电池充电」不够可控，想要免费开源、可自托管逻辑的工具党。

## 如何使用

### 前置条件

- **Apple Silicon Mac**（M1/M2/M3 等）；**不支持 Intel Mac**
- macOS，首次安装 GUI 或 CLI 时需要**管理员密码**（安装 SMC 组件到 `/usr/local/bin`）
- 若使用 Little Snitch 等防火墙，需放行 GitHub、更新服务器等 HTTPS 请求（阻断仅影响自动更新）

### 安装方式

**方式一：Homebrew 安装 GUI（推荐）**

```bash
brew install battery
```

安装后需**打开一次菜单栏应用**以完成组件安装；首次启动会请求管理员密码。

**方式二：下载 DMG**

从 [Releases](https://github.com/actuallymentor/battery/releases/) 下载安装包，打开应用完成初始化。

**方式三：仅安装 CLI**

```bash
curl -s https://raw.githubusercontent.com/actuallymentor/battery/main/setup.sh | bash
```

脚本会下载预编译 `smc` 工具并安装 `smc` 与 `battery` 到 `/usr/local/bin`。

### 首次运行

**GUI**：打开 Battery 应用，输入管理员密码；应用会将电量放电至 80%（即使正插电），之后自动维持上限。

**CLI**：设定维持 80% 充电上限（重启后仍生效）：

```bash
battery maintain 80
```

查看当前状态：

```bash
battery status
```

### 验证是否成功

- 运行 `battery status` 查看 SMC 状态与电量百分比
- 执行 `battery charging off` 后，菜单栏电池图标应显示「未在充电」；`battery charging on` 后恢复充电图标
- 插电且电量高于设定上限时，电量应逐渐下降或不再上升

### 常见坑 / 注意事项

- **仅 Apple Silicon**：Intel Mac 无法使用，请改用 AlDente 等工具。
- **旧版路径/权限问题**：若升级前版本异常，可执行 `sudo rm -rf ~/.battery` 并删除 `/usr/local/bin/smc` 与 `/usr/local/bin/battery` 后重新安装。
- **自定义百分比**：非 80% 的上限或区间（如 `battery maintain 70-80`）**只能通过 CLI** 设置，GUI 默认维持 80%。
- **隐私与网络**：GUI 会向自托管分析、GitHub 等发起 HTTPS 请求以统计安装量与检查更新；详见 README FAQ。
- **卸载**：`battery uninstall` 可恢复充电并移除已安装组件。

---

# Sink

> 基于 Cloudflare 的轻量短链服务，含访问分析与 AI 生成 Slug，100% Serverless 部署。

- 页面：https://www.niceshare.site/github/sink/
- 仓库：https://github.com/miantiao-me/Sink
- 官网：https://sink.cool
- 语言：TypeScript
- Stars：6800
- 许可证：AGPL-3.0
- 标签：开发工具、自动化、AI 编程
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

[Sink](https://sink.cool) 是一款完全运行在 [Cloudflare](https://www.cloudflare.com/) 上的短链接服务：用 Workers KV 存链、Analytics Engine 做统计，Nuxt 构建管理后台与跳转页。它把「缩短 URL → 自定义 Slug → 查看点击分析 → 生成社交预览」收成一套 Serverless 方案，无需自建 VPS 或数据库。项目曾登上 Hacker News 与 HelloGitHub，提供在线 Demo（[sink.cool/dashboard](https://sink.cool/dashboard)）与浏览器扩展、Raycast、iOS App 等生态扩展。

## 核心特性

- **短链与自定义 Slug**：压缩长 URL，支持个性化路径、UTM 参数与大小写敏感设置
- **访问分析**：实时事件日志、3D 地球可视化、按链接导出 CSV，满足基础营销归因需求
- **链接管控**：过期时间、访问密码、不安全链接警告页；按设备或国家智能跳转
- **社交预览**：自定义 OpenGraph 标题、描述与图片；可选 R2 存储 OG 图片
- **AI 辅助**：基于 Cloudflare Workers AI 从页面内容生成 Slug 与 OG 元数据
- **批量迁移**：JSON 导入/导出链接；内置 API 与 OpenAPI 文档，可接 MCP 代理
- **多语言**：管理后台与跳转页完整 i18n；附带 QR 码生成

## 对用户价值

自建短链往往要在「付费 SaaS」「PHP 自托管」与「手写 Workers 脚本」之间取舍：前者按量计费且数据不在自己手里，后者运维成本高或功能单薄。Sink 把短链、分析、预览与 AI 能力打包进 Cloudflare 免费/低成本套餐，Fork 后按文档绑定 KV、Analytics Engine 即可上线独立域名。对个人站长，它适合博客外链、活动落地页与社交分享；对团队，统一 API 与批量导入降低从 Bitly 等平台的迁移摩擦。AGPL-3.0 许可意味着若你修改后对外提供网络服务，需开放相应源码。

## 与替代方案

- 相比 **Bitly、Dub.co** 等**商业短链 SaaS**，Sink **自托管、数据在自家 Cloudflare 账号**，无按点击量阶梯定价，但需自行维护 Fork 与环境变量，且无官方托管 SLA。
- 相比 **YOURLS、Shlink** 等**传统 PHP 自托管**，Sink **无服务器、无 MySQL**，冷启动与全球边缘跳转更轻，但深度依赖 Cloudflare 生态（KV、Analytics Engine、可选 Workers AI / R2）。
- 相比**纯 Workers 脚本或 n8n 拼出来的跳转**，Sink 提供完整 Dashboard、实时分析、密码/过期/地理路由与 OG 定制，适合不想从零写管理界面的场景。
- 若只需**内网或极简跳转**、不需要统计与后台，手写 `wrangler` 路由或静态重定向更轻；若需要企业级团队协作与合规审计，商业平台仍更合适。

## 适应人群

- 拥有 Cloudflare 账号、希望用自有域名提供短链与基础分析的博主与独立开发者。
- 从 Bitly 等平台迁移、需要批量导入与 API 集成的运营或增长同学。
- 已使用 Nuxt / Cloudflare Workers 技术栈、愿意 Fork 定制跳转逻辑与 AI Slug 规则的前端或全栈工程师。

## 如何使用

### 前置条件

- [Cloudflare](https://dash.cloudflare.com/) 账号与可绑定的自定义域名（或使用 `*.workers.dev` 子域）
- [GitHub](https://github.com/) 账号，用于 Fork 仓库并连接 Cloudflare 构建
- Node.js **≥ 22**（本地构建或调试时；Cloudflare 构建环境会按项目配置执行 `pnpm run build` 或 `npm run build`）
- 在 Cloudflare 控制台创建 **KV 命名空间**；启用 **Analytics Engine**（免费档即可）
- 准备至少 8 位的 `NUXT_SITE_TOKEN`（Dashboard 登录令牌）、`NUXT_CF_ACCOUNT_ID` 与具备 Analytics 权限的 `NUXT_CF_API_TOKEN`

### 安装方式

**推荐：Cloudflare Workers 部署**

1. Fork 仓库：[miantiao-me/Sink](https://github.com/miantiao-me/Sink/fork)
2. 在 Cloudflare 创建 [KV 命名空间](https://developers.cloudflare.com/kv/)，将 `wrangler.jsonc` 中的 `kv_namespaces` ID 替换为你的命名空间 ID
3. （可选）创建名为 `sink` 的 [R2 桶](https://developers.cloudflare.com/r2/)用于 OG 图片上传；不需要可在 `wrangler.jsonc` 注释 `r2_buckets`
4. 在 [Cloudflare Workers](https://developers.cloudflare.com/workers/) 新建项目，连接 Fork 后的 `Sink` 仓库：
   - **Build command**：`pnpm run build` 或 `npm run build`
   - **Deploy command**：`npx wrangler deploy`
5. 部署后在 **Settings → Variables and Secrets** 添加环境变量（见下方「首次运行」）
6. 在账号侧启用 **Analytics Engine**，数据集名 `sink`（或通过 `NUXT_DATASET` 自定义，并同步 `wrangler.jsonc`）
7. 重新部署使绑定与变量生效

**备选：Cloudflare Pages 部署**

详见仓库 [Pages 部署文档](https://github.com/miantiao-me/Sink/blob/master/docs/deployment/pages.md)：选择 Nuxt 预设，绑定 KV / Analytics Engine /（可选）Workers AI 与 R2，并设置 Compatibility flag `nodejs_compat`。

**本地开发（可选）**

```bash
git clone https://github.com/miantiao-me/Sink.git
cd Sink
pnpm install
cp .env.example .env   # 按 docs/configuration.md 填写
pnpm dev
```

### 首次运行

1. 完成 Workers 或 Pages 部署并绑定 KV、Analytics Engine
2. 在环境变量中设置：
   - `NUXT_SITE_TOKEN`：Dashboard 访问令牌（≥ 8 字符）
   - `NUXT_CF_ACCOUNT_ID`：Cloudflare 账户 ID
   - `NUXT_CF_API_TOKEN`：至少含 `Account.Account Analytics` 权限的 API Token
3. 带 `NUXT_PUBLIC_` 前缀的变量（如 `NUXT_PUBLIC_HOME_URL` 自定义首页）在 Workers 场景下需同时配置在 **Build** 与 **Runtime** 的 Variables and Secrets
4. 打开 `https://<你的域名>/dashboard`，使用 `NUXT_SITE_TOKEN` 登录
5. 创建第一条短链，可选开启 AI 生成 Slug（需绑定 Workers AI）或自定义 OG 预览

### 验证是否成功

- 访问生成的短链 URL，确认跳转到目标长链且状态码符合预期（默认 301，可通过 `NUXT_REDIRECT_STATUS_CODE` 调整）
- 在 Dashboard 的 **Analytics** 中看到点击事件与实时日志
- 调用 [API 文档](https://github.com/miantiao-me/Sink/blob/master/docs/api.md) 中的接口（携带 Site Token）能创建/列出链接
- 在线 Demo 可参考官方站点：Token `SinkCool` 登录 [sink.cool/dashboard](https://sink.cool/dashboard)

### 常见坑 / 注意事项

- **Analytics 无数据**：确认已启用 Analytics Engine 并完成数据集绑定，修改后需重新部署
- **Workers 环境变量分层**：`NUXT_PUBLIC_*` 在 Worker 部署下要同时配 Build 与 Runtime，否则前端读不到
- **KV 批量导入上限**：默认单次 KV 操作上限 50（`NUXT_PUBLIC_KV_BATCH_LIMIT`），大批量迁移需分批
- **链接缓存延迟**：`NUXT_LINK_CACHE_TTL` 默认 60 秒，改链后可能不会立即生效
- **AGPL-3.0**：对外提供修改版网络服务时需遵守 Affero 开源义务；仅内部使用或不做网络分发则约束较轻
- **Demo 模式**：`NUXT_PUBLIC_PREVIEW_MODE` 下链接 5 分钟过期且不可编辑，勿在生产误开
- 更多问题见仓库 [FAQs](https://github.com/miantiao-me/Sink/blob/master/docs/faqs.md) 与 [配置说明](https://github.com/miantiao-me/Sink/blob/master/docs/configuration.md)

---

# WASI

> WebAssembly 系统接口标准，为 Wasm 模块提供类 POSIX 的宿主能力，正由 WebAssembly 社区推进标准化。

- 页面：https://www.niceshare.site/github/wasi/
- 仓库：https://github.com/WebAssembly/WASI
- 官网：https://webassembly.org/
- 语言：Rust
- Stars：5694
- 许可证：NOASSERTION
- 标签：开发工具、系统编程、跨平台
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

WASI（WebAssembly System Interface）是由 [WebAssembly Community Group](https://www.w3.org/community/webassembly/) 旗下 **WASI Subgroup** 制定的一套系统级 API 标准，目标是为 WebAssembly 模块提供安全、可移植的宿主能力（文件、时钟、网络、HTTP 等），设计思路深受 POSIX 与 [CloudABI](https://cloudabi.org/) 影响。本仓库承载**总体讨论、治理流程与高层目标**；各具体 API 在独立提案仓库中演进，可在 [Proposals 列表](https://github.com/WebAssembly/WASI/blob/main/docs/Proposals.md) 查阅。当前主线为 **WASI 0.3**（Preview 3），在 0.2 模块化 Wit 接口基础上引入 Component Model 原生的 `async` 能力。

## 核心特性

- **分阶段标准化流程**：提案经历 Phase 0–5（预提案 → 标准化），与 WebAssembly CG 流程对齐，便于社区审阅与实现跟进
- **三代预览演进**：Preview 1（witx IDL，已广泛部署）→ [WASI 0.2](https://github.com/WebAssembly/WASI/tree/wasi-0.2)（[Wit IDL](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md) 模块化 API）→ WASI 0.3（`future` / `stream` 原生异步）
- **模块化 API 集合**：Phase 3 实现中的核心包包括 CLI、Clocks、Filesystem、Random、Sockets、HTTP 等；另有 KV、TLS、SQL、机器学习（wasi-nn）等扩展提案
- **跨语言与可虚拟化**：Wit 类型系统比 witx 更具表达力，支持更多源语言编译目标，并强调接口可被宿主虚拟化以实现安全沙箱
- **开放提案机制**：新 API 通过 [wasi-proposal-template](https://github.com/WebAssembly/wasi-proposal-template) 发起，遵循 [Contributing 指南](https://github.com/WebAssembly/WASI/blob/main/CONTRIBUTING.md) 与 [Charter](https://github.com/WebAssembly/WASI/blob/main/Charter.md) 范围约束

## 对用户价值

若你需要让 WebAssembly 模块在浏览器之外运行——云函数、边缘节点、插件系统、嵌入式沙箱——WASI 提供了**与宿主解耦的标准契约**，避免每个运行时各自发明 syscall。对运行时开发者（[Wasmtime](https://github.com/bytecodealliance/wasmtime)、[WasmEdge](https://github.com/WasmEdge/WasmEdge) 等），WASI 是能力对齐的参照；对应用与工具链作者，可按预览版本选择目标接口并评估迁移成本。本仓库本身不提供可执行运行时，而是规范与治理的「单一信息源」。

## 与替代方案

- 相比 **各运行时私有 syscall**（如早期 Emscripten 定制接口），WASI 推动跨实现一致性与可移植二进制，降低「换运行时就要改集成」的成本；代价是标准化周期长，前沿能力往往先以提案形式存在。
- 相比 **直接 POSIX / 完整操作系统 API**，WASI 刻意裁剪权限（能力安全、最小暴露面），更适合不可信代码沙箱；需要完整系统调用或遗留 C 库直链时，原生 POSIX 或容器仍更合适。
- 相比 **[WASI Preview 1（witx）](https://github.com/WebAssembly/WASI/tree/wasi-0.1)**，0.2/0.3 基于 Component Model 与 Wit，模块边界与异步模型更清晰；大量生产环境仍停留在 Preview 1，升级需对照各运行时的 0.2/0.3 支持矩阵。
- 相比 **浏览器 Web API**（Fetch、WebCrypto 等），WASI 面向非浏览器宿主；在浏览器内运行 Wasm 通常走 JS/Wasm 互操作而非完整 WASI 栈。
- 边界说明：实现 WASI 的是**运行时与 SDK**，本 repo 用于读规范、跟提案与参与标准讨论，而非 `apt install wasi` 一类安装。

## 适应人群

- 维护或选型 Wasm 运行时、serverless 平台、插件市场的基础设施工程师，需要跟踪 HTTP/Sockets/Filesystem 等 API 成熟度。
- 使用 Rust、C/C++、TinyGo 等将程序编译为 Wasm 并部署到边缘/云端的系统开发者，需理解目标预览版本与工具链支持。
- 希望向 WebAssembly 社区提交新系统 API、参与 Phase 流程或实现提案的标准贡献者与架构师。

## 如何使用

### 前置条件

- 了解 [WebAssembly](https://webassembly.org/) 基础概念；跟进 0.2/0.3 时建议先阅读 [Component Model](https://github.com/WebAssembly/component-model) 与 [Wit 文档](https://component-model.bytecodealliance.org/)。
- 参与提案讨论需熟悉 [WASI Contributing](https://github.com/WebAssembly/WASI/blob/main/CONTRIBUTING.md) 与 [Phase Process](https://github.com/WebAssembly/WASI/blob/main/CONTRIBUTING.md#the-phase-process)。
- **运行 Wasm 程序**需单独安装实现 WASI 的运行时（如 Wasmtime）；本仓库仅为规范与元数据，不包含可执行二进制。

### 安装方式

**克隆本仓库（阅读规范与提案索引）**

```bash
git clone https://github.com/WebAssembly/WASI.git
cd WASI
```

浏览 `docs/Proposals.md` 获取各 API 独立仓库链接；历史预览可切换分支/tag：`wasi-0.1`、`wasi-0.2`。

**安装 WASI 运行时（实际执行 Wasm 模块，以 Wasmtime 为例）**

```bash
curl https://wasmtime.dev/install.sh -sSf | bash
```

其他实现见 [Bytecode Alliance](https://bytecodealliance.org/) 与 [WasmEdge 文档](https://wasmedge.org/docs/)；选型时核对目标 WASI 预览版本支持情况。

### 首次运行

1. 在 `docs/Proposals.md` 中定位所需 API（如 `wasi-http`、`wasi-filesystem`），进入对应提案仓库阅读 Wit 定义与示例。
2. 使用工具链将代码编译为带 WASI 目标的 Wasm（例如 `cargo build --target wasm32-wasip1` 或各语言文档推荐命令）。
3. 用已安装的运行时执行产物，例如：`wasmtime run ./app.wasm`（具体标志因预览版本而异，以运行时文档为准）。

### 验证是否成功

- 能在 Proposals 列表中找到目标 API 的 Phase 与版本列（如是否纳入 WASI 0.3）。
- 运行时 `--version` 或文档标明支持的 WASI 预览级别，且示例 Wasm 可正常启动、访问声明的能力（文件/网络等）。
- 若参与社区流程：可在 [WASI Issues](https://github.com/WebAssembly/WASI/issues) 检索相关 `P-*` 标签提案讨论是否活跃。

### 常见坑 / 注意事项

- **预览版本混用**：Preview 1（witx）与 0.2/0.3（Wit + Component Model）ABI 不兼容；构建目标、运行时与依赖需同一预览线，否则易出现链接或启动失败。
- **本仓库非实现仓库**：具体 API 的 breaking change 发生在各 `wasi-*` 提案仓库；订阅读取本 repo README 不足以集成生产，需跟进子仓库 Releases。
- **能力安全模型**：WASI 强调最小权限；默认可能无网络或文件系统访问，需在宿主配置中显式授予 capability。
- **许可证**：仓库元数据显示 `NOASSERTION`；各提案子仓库许可证可能不同，商业集成前请逐包核对。
- **异步迁移（0.3）**：0.3 用 Component Model 的 `future`/`stream` 替代早期显式 poll 接口；升级路径与运行时支持仍在演进，生产环境宜保守锁定版本。

---

# Kaneo

> 开源自托管项目管理工具，对标 Linear/Jira 的极简看板，强调少而精与数据自主。

- 页面：https://www.niceshare.site/github/kaneo/
- 仓库：https://github.com/usekaneo/kaneo
- 官网：https://kaneo.app/
- 语言：TypeScript
- Stars：5548
- 许可证：MIT
- 标签：自托管、开发工具、工作流
- 收录：2026-08-02（更新于 2026-08-02）

## 项目介绍

Kaneo 是一款 MIT 许可的开源项目管理工具，定位「你需要的都在，多余的都没有」。它面向受够臃肿平台的小团队与独立开发者，提供干净的看板式工作流，并支持自托管，让 issue、项目与团队数据留在自己的基础设施上。官方另有 [Cloud](https://cloud.kaneo.app) 与完整文档（[kaneo.app/docs](https://kaneo.app/docs/core)）。

## 核心特性

- **极简界面** — 减少多余按钮与通知噪音，把注意力留在交付本身
- **可自托管** — Docker Compose / drim 一键部署，数据与密钥由你掌控
- **性能优先** — TypeScript 栈（React + Hono），强调实际可用的响应速度
- **开源许可** — MIT，便于二次开发与商业自用
- **多部署路径** — 支持 drim、Docker Compose、Helm（Kubernetes）与本地 `pnpm` 开发

## 对用户价值

多数项目管理工具的问题不是功能不够，而是功能过多：复杂工作流、无休止的通知与配置，反而拖慢交付。Kaneo 把「看板 + issue」收敛成轻量自托管方案，适合不想被 Jira/Linear 的 SaaS 费用或供应商锁定绑架、又需要一个干净协作面板的团队。数据驻留在自有 PostgreSQL 上，也便于合规与备份。

## 与替代方案

- 相比 **[Linear](https://linear.app/)**：Linear 产品体验成熟、偏 SaaS；Kaneo 开源可自托管，更适合要数据自主或控制成本的团队。
- 相比 **Jira**：Jira 企业流程与插件生态更全，但配置沉重；Kaneo 刻意做减法，不适合重度流程编排与复杂权限矩阵。
- 相比 **Plane / Focalboard 等开源看板**：选型时对比 UI 完成度、issue 模型与运维成本；Kaneo 的卖点是「少而精 + MIT + 官方 Cloud 可选」。
- **边界**：若你需要完整 OKR、工时报表、复杂审批链，应继续评估企业级套件，而非强行用 Kaneo 替代。

## 适应人群

- 想替换臃肿项目管理 SaaS、偏好自托管的小团队与创业公司。
- 需要轻量 issue / Kanban、但不想维护复杂插件生态的工程负责人。
- 希望在 Homelab 或内网快速搭一套看板，并保留 Cloud 试用出口的独立开发者。

## 如何使用

### 前置条件

- Docker 与 Docker Compose（试用 / 生产推荐），或可运行 [drim](https://github.com/usekaneo/drim) 的环境。
- PostgreSQL（Compose 会一并拉起）；生产建议准备域名与 HTTPS。
- 生成会话密钥：`openssl rand -hex 32`（写入 `AUTH_SECRET`）。

### 安装方式

**方式一：drim 一键部署（官方推荐，含自动 HTTPS 与数据库配置）**

```bash
curl -fsSL https://assets.kaneo.app/install.sh | sh
drim setup
```

**方式二：Docker Compose 快速试用**

将官方 README 中的 `compose.yml` 保存到本地，复制 `.env.sample` 为 `.env`，取消注释 `KANEO_CLIENT_URL=http://localhost:5173`，设置 `POSTGRES_PASSWORD` 与 `AUTH_SECRET`，然后：

```bash
docker compose up -d
```

浏览器打开 `http://localhost:5173`。Compose 内 API 通过服务名 `postgres` 连库；若 API 跑在宿主机，请改用 `localhost` 或显式设置 `DATABASE_URL`。

**方式三：本地开发**

```bash
git clone https://github.com/usekaneo/kaneo.git
cd kaneo
pnpm install
# 按 ENVIRONMENT_SETUP.md 配置根目录 .env
pnpm dev
```

Kubernetes 场景可使用仓库内 Helm chart（见 `charts/kaneo/`）。

### 首次运行

打开 Web 界面完成初始账号/工作区设置，创建第一个项目与看板列，试着新建一条 issue 并拖拽状态。可选配置 GitHub OAuth（`GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET`）以启用 SSO。

### 验证是否成功

- 页面可访问且能登录；新建 issue 可保存并在看板间移动。
- `docker compose ps`（或 drim 状态）显示 Postgres 与 Kaneo 容器健康。
- 重启后会话仍有效（确认 `AUTH_SECRET` 已固定写入 `.env`，而非每次随机生成）。

### 常见坑 / 注意事项

- **未固定 `AUTH_SECRET`**：启动时会随机生成，重启后已有会话全部失效。
- **数据库主机名**：Compose 内用 `postgres`，宿主机直连 API 时用 `localhost` / 显式 `DATABASE_URL`，混用会导致连库失败。
- **CORS / 环境变量**：本地开发常见跨域问题，详见仓库 [ENVIRONMENT_SETUP.md](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md)。
- **生产加固**：务必改默认密码、启用 HTTPS，并参考 [官方文档](https://kaneo.app/docs/core) 配置环境变量；管道安装脚本请先审阅再执行。

---

# Arya

> 基于 Vditor 的在线 Markdown 编辑器，支持流程图、图表与 PPT 预览，可自托管。

- 页面：https://www.niceshare.site/github/markdown-online-editor/
- 仓库：https://github.com/nicejade/markdown-online-editor
- 官网：https://markdown.lovejade.cn
- 语言：CSS
- Stars：3702
- 许可证：MIT
- 标签：知识管理、开发工具、工作流
- 收录：2026-06-20（更新于 2026-06-20）

## 项目介绍

Arya（二丫）是由 nicejade 基于 Vue2 与 [Vditor](https://github.com/Vanessa219/vditor) 构建的开源在线 Markdown 编辑器。它把所见即所得编辑、分屏预览、流程图与 ECharts 图表、PPT 预览、HTML 转 Markdown 等能力整合在一个浏览器页面里，既可直接使用官方托管站点，也支持 Docker 或静态托管自部署。

## 核心特性

- 完整 Markdown 语法支持，含流程图、甘特图、时序图与任务列表
- 所见即所得、即时渲染、分屏预览三种编辑模式，可快捷键切换
- 粘贴 HTML 自动转 Markdown，支持 ECharts 图表、五线谱与部分音视频嵌入
- 内置 Reveal.js PPT 预览，可导出带样式 PDF、PNG、JPEG 与 Word（.docx）
- 编辑内容本地存储防丢失，支持导入本地 `.md` 与复制到微信公众号
- 提供 Docker 镜像、PM2 与 Cloudflare Pages 等多种部署方式

## 对用户价值

Arya 把「写 Markdown」和「排版发布」放在同一界面：技术文档可即时预览图表与代码块，内容创作者可一键适配公众号格式，团队则可用 Docker 或静态托管在内网快速落地，无需订阅商业编辑器的高级功能。

## 与替代方案

- 相比 Typora、Obsidian 等桌面客户端，Arya 是浏览器优先方案，零安装即可使用，自托管后可完全掌控数据。
- 相比 StackEdit、HackMD 等在线编辑器，Arya 基于 Vditor，在 ECharts、PPT 预览、HTML 转换与公众号导出上功能更完整，且 MIT 开源可 Fork。
- 相比仅做预览的 marked/showdown 类库，Arya 是开箱即用的完整编辑器；若只需 CLI 转换，轻量工具链可能更合适。

## 适应人群

- 需要写技术文档、博客草稿并即时预览图表的开发者。
- 经常向微信公众号等平台排版发布的内容创作者。
- 希望在内网或 Cloudflare Pages 上自托管 Markdown 编辑器的团队。

## 如何使用

### 前置条件

- **在线使用**：现代浏览器即可，无需安装。
- **本地开发**：Node.js >= 16 且 < 18，推荐 yarn 或 pnpm。
- **Docker 部署**：已安装 Docker（可选 Docker Compose）。

### 安装方式

**Docker 快速启动（推荐）：**

```shell
docker run -d -p 8866:80 nicejade/markdown-online-editor:latest
```

**源码构建 + PM2 部署：**

```bash
git clone https://github.com/nicejade/markdown-online-editor.git
cd markdown-online-editor
yarn
yarn global add pm2
yarn build
yarn release
```

**本地开发：**

```bash
git clone https://github.com/nicejade/markdown-online-editor.git
cd markdown-online-editor
yarn
yarn start
```

### 首次运行

- Docker：浏览器访问 `http://localhost:8866`。
- 开发模式：`yarn start` 后按终端提示打开本地地址。
- 清空编辑区默认文档即可开始写作；默认所见即所得模式，可用 `⌘-⇧-M`（Windows/Linux：`Ctrl-⇧-M`）切换编辑模式。

### 验证是否成功

- 输入 Markdown 文本，确认实时预览正常渲染。
- 插入流程图或任务列表语法，检查图表是否正确显示。
- 尝试导出 PDF 或复制到微信公众号，确认输出格式符合预期。

### 常见坑 / 注意事项

- 本地开发要求 Node.js < 18；Cloudflare Pages 构建需设置 `NODE_VERSION=18` 与 `NODE_OPTIONS=--openssl-legacy-provider`。
- PPT 预览暂不支持各类图表渲染，幻灯片用 `---`（水平）与 `--`（垂直）分隔，详见 [Reveal.js Markdown 文档](https://revealjs.com/markdown/)。
- Docker 映射端口可自定义，生产环境建议配合反向代理与 HTTPS。
- 项目基于 Vue2，长期维护需关注上游 Vditor 与依赖安全更新。

---

# opencodex

> 本地通用 LLM 代理，让 Codex 与 Claude Code 接入 Claude、Gemini、Ollama 等任意模型。

- 页面：https://www.niceshare.site/github/opencodex/
- 仓库：https://github.com/lidge-jun/opencodex
- 官网：https://lidge-jun.github.io/opencodex/
- 语言：TypeScript
- Stars：1889
- 许可证：MIT
- 标签：AI 编程、CLI、本地模型
- 收录：2026-07-21（更新于 2026-07-21）

## 项目介绍

opencodex 是面向 OpenAI Codex 与 Claude Code 的轻量本地代理：把 Codex Responses API（以及 Claude Code 的 Anthropic Messages API）翻译成各家 LLM 协议，从而在不改工作流的前提下接入 Claude、Gemini、Grok、DeepSeek、Kimi、Qwen、Ollama 等 40+ 提供商。它支持流式、工具调用、reasoning token 与图片，并可池化多个 ChatGPT / Codex 账户做配额感知路由。项目 MIT 开源，文档提供中英韩三语。

## 核心特性

- **任意模型进 Codex / Claude Code**：5 种协议 adapter 覆盖 Anthropic、Gemini、Azure、OpenAI Responses 与 OpenAI 兼容 Chat Completions；`ocx claude` 可启动已接线的 Claude Code
- **40+ 内置 Provider + 自定义端点**：仪表盘一键添加；Anthropic / xAI / Kimi 支持 OAuth，也可粘贴 API Key 或 `${ENV_VAR}` 引用
- **ChatGPT 账户池**：新会话按 5h / 周 / 30d 配额挑健康账号，已有线程保持 affinity；429 冷却与 failover，token 失败 fail-closed
- **模型路由与子代理委派**：`provider/model` 语法（如 `anthropic/claude-opus-4-8`、`ollama/llama3`）；最多 5 个模型进 Codex subagent 选择器
- **Web 仪表盘与干净退出**：`localhost:10100` 看请求日志与 OAuth 状态；`ocx stop` / `ocx uninstall` 可恢复原生 Codex 配置，无残留

## 对用户价值

官方 Codex 与 Claude Code 体验好，但模型与账号往往绑死。opencodex 让你继续用同一套 CLI / App / SDK，却能自由换大脑：本地 Ollama 试跑、第三方 API 控成本、多 ChatGPT 账号分担配额，都不必等官方加支持。对已深度使用 Codex 工作流、又不想迁到另一套 Agent 产品的人，它是「换引擎、不换方向盘」的路径。

## 与替代方案

- 相比 **CC Switch**：CC Switch 侧重多 CLI 的供应商配置管理与桌面快切；opencodex 是运行时本地代理，直接把请求翻译并路由到任意模型，还能池化 Codex 登录账号。
- 相比直接改 **Codex / Claude Code 配置或第三方中继**：opencodex 自动注入客户端、提供仪表盘与按需 shim，并保留 `ocx stop` 一键还原；中继方案通常不覆盖 Claude Code Messages API 与 Codex 账户池。
- 相比 **OpenCode、Aider** 等独立开源 Agent：那些是另一套产品体验；若你已习惯官方 Codex / Claude Code，opencodex 更适合「保留宿主、只换模型」。
- 若只需单一官方订阅、从不换模型，直接官方登录更轻量，无需引入本地代理。

## 适应人群

- 日常用 Codex CLI / App，却想试用 Claude、Gemini、DeepSeek 或本地 Ollama 的开发者。
- 同时维护多个 ChatGPT / Codex 账号，需要配额感知路由与会话亲和的重度用户。
- 已在用 Claude Code，希望同一守护进程里切换路由模型、又不想迁移到其他 Agent 的人。

## 如何使用

### 前置条件

- Node.js 18+（推荐 nvm / fnm 等用户自有 Node，避免 `sudo npm install -g`）
- 已安装 [Codex](https://github.com/openai/codex) 和/或 Claude Code；Windows / macOS / Linux 原生支持（Windows 无需 WSL）
- 至少一个可用凭证：ChatGPT / Codex 登录、Provider API Key，或本地 Ollama 等端点

### 安装方式

```bash
# 自动打包 Bun 运行时，只需 Node 18+
npm install -g @bitkyc08/opencodex
```

若出现 `bundled Bun runtime is missing`（安装时跳过了 lifecycle / optional 依赖），允许 bun 脚本后重装：

```bash
npm install -g --allow-scripts=bun @bitkyc08/opencodex
```

完整文档：[lidge-jun.github.io/opencodex](https://lidge-jun.github.io/opencodex/)

### 首次运行

```bash
ocx init          # 交互式写入配置并注入 Codex
ocx start         # 默认监听 localhost:10100
ocx gui           # 打开仪表盘，添加 Provider / 管理账户池
# 可选：按需自动启动代理
ocx codex-shim install
```

之后正常使用 Codex；指定路由模型示例：

```bash
codex -m "anthropic/claude-opus-4-8" "解释这个 stack trace"
codex -m "ollama/llama3" "重构这个函数"
```

Claude Code：`ocx claude` 启动已接入代理的会话（需 Claude Code 2.1.129+ 以使用网关模型发现）。

### 验证是否成功

- `ocx status` 显示代理在运行；浏览器打开 `http://localhost:10100` 能看到仪表盘
- 在 Codex 中执行简单任务，或用 `-m "provider/model"` 指定路由模型并得到响应
- 仪表盘请求日志出现对应上游调用；无阻塞性鉴权 / 连接错误

### 常见坑 / 注意事项

- **Bun 运行时缺失**：不要用 `--ignore-scripts` / `--omit=optional`；重装时务必显式带上包名 `@bitkyc08/opencodex`
- **sudo 全局安装**：root 前缀易导致脚本与权限问题，优先迁移到用户级 Node
- **干净卸载**：试用结束后用 `ocx stop` 或 `ocx uninstall`，避免遗留注入配置
- **跨 Provider 委派限制**：原生父代理 spawn 路由子代理时，任务正文可能因后端加密丢失（[#92](https://github.com/lidge-jun/opencodex/issues/92)）；可靠跨模型委派请关注文档中的 v1 表面说明
- **密钥与账户**：OAuth token、API Key 与账户池凭证保存在本地配置中，勿提交到仓库

---

# Comet

> 将 OpenSpec 与 Superpowers 串联为五阶段 Agent Skill 工作流，从想法到归档全程可恢复、可校验。

- 页面：https://www.niceshare.site/github/comet/
- 仓库：https://github.com/rpamis/comet
- 官网：https://www.npmjs.com/package/@rpamis/comet
- 语言：TypeScript
- Stars：1479
- 许可证：MIT
- 标签：AI 编程、Agent、工作流
- 收录：2026-06-19（更新于 2026-06-19）

## 项目介绍

Comet（`@rpamis/comet`）是面向 AI 编程场景的 Agent Skill 编排工具。它把 OpenSpec 的「做什么」（大纲、提案、Spec 生命周期与归档）与 Superpowers 的「怎么做」（技术设计、规划、执行与收尾）串成五阶段自动化流水线，并用阶段守卫脚本校验状态，避免代理仅凭口头确认就推进流程。

主入口 `/comet` 支持读取当前 Spec 状态并从中断处继续，适合跨会话的长任务开发。

## 核心特性

- 五阶段流水线：从想法到归档，OpenSpec + Superpowers 自动衔接
- 阶段守卫脚本，不依赖代理自述「已完成」
- `.comet.yaml` 记录阶段、执行模式与验证结果，支持断点恢复
- 可配置审查模式（`off` / `standard` / `thorough`）控制 Build/Verify 代码审查强度
- 研究型示例：嵌套 Skill 触发、跨阶段自动交接与文档同步自动化

## 对用户价值

对日常用 Cursor、Claude Code 等 AI 编程工具的用户，Comet 把「写 Spec → 设计 → 实现 → 验证 → 归档」从反复提醒代理同步文档，变成可脚本化、可恢复的流程，减少会话中断后重新读文档、猜进度的 token 浪费。

对 Skill 作者而言，它也是可参考的实现：如何可靠触发嵌套 Skill、如何在阶段间自动交接，以及如何把脆弱流程从 Prompt 抽到可测试的 Shell 脚本里。

## 与替代方案

- 相比单独使用 OpenSpec 或 Superpowers，Comet 提供二者协同的编排层与状态机。
- 相比纯 Prompt 约定流程，阶段守卫脚本更可验证、可恢复。
- 若团队不使用 Cursor/Superpowers 生态，接入成本较高，需评估 Skill 兼容性。

## 适应人群

- 已在使用 OpenSpec 或 Superpowers，希望两者协同而非二选一的开发者。
- 需要可中断、可恢复的 Spec 驱动开发流程的团队。
- 想研究 Agent Skill 安装分发与阶段状态机设计的工具作者。

## 如何使用

### 前置条件

- Node.js 20+、npm。
- Bash 兼容终端（Windows 建议 Git Bash）。
- 项目中已安装或计划安装 OpenSpec 与 Superpowers 相关 Skill。

### 安装方式

```bash
npm install -g @rpamis/comet
```

在项目根目录执行：

```bash
comet init
```

### 首次运行

在 AI 编程会话中输入 `/comet` 启动或恢复流程；Comet 会读取 `.comet.yaml` 与 OpenSpec 工件，从中断阶段继续。

### 验证是否成功

完成一个小需求的全流程后，检查各阶段守卫是否通过、Spec 是否归档，以及 `.comet.yaml` 状态与预期一致。

### 常见坑 / 注意事项

- 审查模式与项目默认需在 `init` 后按 README 配置，避免 Verify 阶段过严或过松。
- 首次接入建议在可回滚分支上跑通，再接入主仓库。
- 平台差异（路径、Shell）请以 README 与 `NEWS.md` 为准；子命令细节需对照官方文档核实。