nosce (Julienandreu)

鼻子

由Claude提供支持的多仓库平台的自动化每日变更日志和架构文档。

如果你的平台被拆分为许多git子模块，那么很难跟踪发生了什么变化——以及它意味着什么。工程师们错过了其他团队的突破性变化。产品经理从Slack线程中拼凑出交付状态。销售人员不知道上周发了什么货。

诺斯解决了这个问题。你把它指向一个包含git子模块的存储库，Claude分析其中的每一个：提交、合并的PR、代码结构、数据库模式、API契约。它产生：

• 日报 --不仅是提交列表，而且按主题摘要分组，解释 _发生了什么变化，为什么重要_，其中嵌入了来自PR的截图和视频。
• 特定角色摘要 --同样的更改，为工程师（破坏性更改、部署风险）、产品经理（功能进度、阻碍）和销售（面向客户的改进、值得演示的功能）重写。
• 架构文档 -服务拓扑图、API契约、数据库模式和依赖关系图，自动保持最新。

结果通过 网页用户界面 对于人类和 MCP服务器 对于其他Claude会话，您可以在任何项目中询问“昨天身份验证服务发生了什么变化？”。

目录

• 先决条件
• 安装
• 快速开始
• 运作原理
• 配置
• 生成报告
• 生成文档
• 浏览结果
• MCP服务器
• 网页用户界面
• 项目结构
• 从源头构建
• 故障排除

先决条件

如果你是 从源代码构建，你还需要 锈 (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh)以及 Node.js 18+ (brew install node 或 ).

安装克劳德代码

选择一种方法：

本机安装（推荐） --后台自动更新：

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

自制：

brew install --cask claude-code

然后在任何项目中启动它 claude。首次使用时，系统会提示您登录。看 code.claude.com/docs 适用于其他平台（Windows、VS Code、JetBrains、桌面应用程序）。

安装

安装脚本（推荐）

安装脚本为您的平台下载最新的预构建二进制文件，验证校验和，并将其放入 ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/julienandreu/nosce/main/install.sh | sh

确保 ~/.local/bin 在你的 PATH。如果不是，请将其添加到您的shell配置文件中(~/.zshrc, ~/.bashrc等等）：

export PATH="$HOME/.local/bin:$PATH"

要安装到其他目录，请执行以下操作：

NOSCE_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/julienandreu/nosce/main/install.sh | sh

GitHub发布

直接从下载预构建的二进制文件 发布页面。二进制文件可用于：

下载 .tar.gz 对于您的平台，那么：

tar xzf nosce-*.tar.gz
sudo mv nosce /usr/local/bin/

码头工人

从包含的Dockerfile构建并运行：

docker build -t nosce .
docker run -v ~/.nosce/output:/data -p 3000:3000 nosce serve

容器暴露端口3000并将数据持久化到 /data。装载输出目录以在重新启动时保留报告。

从源代码构建

如果您更喜欢从源代码构建，请参阅 从源头构建.

快速开始

这将使您在5分钟内从零生成报告。

# 1. Install nosce
curl -fsSL https://raw.githubusercontent.com/julienandreu/nosce/main/install.sh | sh

# 2. Create the output directory
mkdir -p ~/.nosce/output

# 3. Clone the repo (needed for Claude Code skills)
git clone https://github.com/julienandreu/nosce.git
cd nosce

# 4. Open Claude Code in this repo
claude

进入Claude Code后，运行：

/sync /path/to/your/platform-repo

替换 /path/to/your/platform-repo 带有指向具有子模块的git存储库的路径。

就是这样。Claude将分析每个子模块，并在 ~/.nosce/output/reports/YYYY-MM-DD.md，加上特定于个人资料的摘要 ~/.nosce/output/reports/YYYY-MM-DD/ 对于每个配置的配置文件（工程师、产品、销售）。

要生成架构文档，请执行以下操作：

/docs /path/to/your/platform-repo

要浏览web UI中的所有内容：

nosce --output-dir ~/.nosce/output serve

打开http://localhost:3000.

运作原理

%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#313244',
  'primaryTextColor': '#cdd6f4',
  'primaryBorderColor': '#585b70',
  'lineColor': '#89b4fa',
  'secondaryColor': '#1e1e2e',
  'tertiaryColor': '#181825',
  'fontFamily': 'ui-monospace, monospace',
  'fontSize': '14px'
}}}%%

flowchart TD
    repo["Your platform repo
with git submodules"]
    claude["Claude Code
/sync    /docs

Reads git history,
PRs, source code.
Analyzes and writes
markdown reports."]
    output["~/.nosce/output/

reports/
  2026-02-28.md
  2026-02-28/
    engineer.md · pm.md · cto.md

media/
  2026-02-28/
    manifest.json · *.png, *.mp4

docs/
  overview.md · architecture.md
  apis.md · databases.md
  dependencies.md
  submodules/
    service-a.md · service-b.md

state.json"]
    mcp["MCP Server
(stdio)

Other Claude
sessions can query"]
    web["Web UI
(HTTP)

Browser at
localhost:3000"]

    repo --> claude
    claude --> output
    output --> mcp
    output --> web

    style repo fill:#45475a,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
    style claude fill:#45475a,stroke:#f5c2e7,stroke-width:2px,color:#cdd6f4
    style output fill:#313244,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
    style mcp fill:#45475a,stroke:#94e2d5,stroke-width:2px,color:#cdd6f4
    style web fill:#45475a,stroke:#fab387,stroke-width:2px,color:#cdd6f4

关键见解克劳德是分析引擎。这 /sync 和 /docs 技能告诉克劳德看什么，克劳德写报告和文档。它不仅列出了提交，还按主题对它们进行了分组，识别了突破性的更改，解释了更改的内容及其重要性，在Mermaid中绘制了架构图，并映射了服务依赖关系。

配置

编辑 nosce.config.yml 在repo根目录中：

version: 1

# Path to the repository containing submodules (can also be passed as CLI arg)
input: /Users/you/github/your-platform

# Where nosce writes reports and docs
output: ~/.nosce/output

# Your GitHub username or org (used by gh CLI for PR lookups)
github_owner: your-org

# Report settings
reports:
  timezone: Europe/Paris

# Which doc categories to generate
docs:
  categories:
    - overview
    - architecture
    - apis
    - databases
    - dependencies

# User profiles — each profile sees a tailored report summary
profiles:
  - id: engineer
    label: Engineer
    icon: wrench
    description: "Technical implementation: code changes, diffs, breaking changes, architecture, testing, deployment risks"
    focus:
      [
        commit_details,
        code_diffs,
        breaking_changes,
        tech_debt,
        architectural_impact,
        test_coverage_impact,
        regression_potential,
        deployment_safety,
      ]
  - id: product
    label: Product
    icon: lightbulb
    description: "Delivery orchestration: feature progress, dependencies, velocity, risk assessment, roadmap alignment"
    focus:
      [
        feature_progress,
        delivery_status,
        blockers,
        cross_team_dependencies,
        risk_assessment,
        sprint_health,
        roadmap_alignment,
        feature_completeness,
      ]
  - id: sales
    label: Sales
    icon: megaphone
    description: "Customer-facing changes: new features, bug fixes, competitive advantages, answers for sales leads"
    focus:
      [
        new_features,
        customer_benefits,
        competitive_advantages,
        release_highlights,
        user_facing_bugs,
        ux_improvements,
        demo_worthy_changes,
      ]

您可以完全跳过编辑此文件，并将路径作为参数传递：

/sync /path/to/repo --output /path/to/output

生成报告

这 /sync 技能

/sync [input-path] [--output path] [--date YYYY-MM-DD]

它的作用：

1. 倒像 .gitmodules 从您的平台仓库中查找所有子模块
2. 对于每个子模块，获取自上次同步以来的新提交
3. 在GitHub上查询合并的PR（如果 gh 已认证）
4. 从公关描述中提取并下载截图/视频
5. Claude分析所有变化，并使用嵌入式媒体生成降价报告

例子：

/sync ~/github/my-platform

你得到了什么 --文件在 ~/.nosce/output/reports/2026-02-28.md:

# Nosce Daily Report — 2026-02-28

> Generated at 2026-02-28T08:00:00Z by Claude

## Summary

- **4** submodules analyzed
- **23** new commits across all submodules
- **7** PRs merged
- Key highlights: New authentication flow deployed in auth-service,
  database migration adds user preferences table in user-service.

---

## auth-service

**Branch**: `main` | **Repo**: `github.com/myorg/auth-service`

### Changes Overview

Major rework of the authentication flow. The team replaced the
session-based auth with JWT tokens (commits by @alice and @bob).
PR #142 introduced the token refresh endpoint. This is a breaking
change for clients that relied on cookie-based sessions.

### Commits (8 new)

| SHA       | Author | Message                      | Date       |
| --------- | ------ | ---------------------------- | ---------- |
| `a1b2c3d` | Alice  | feat: JWT token generation   | 2026-02-28 |
| `e4f5g6h` | Bob    | feat: token refresh endpoint | 2026-02-28 |

| ...

### Merged PRs (3)

- **#142** — JWT authentication (@alice, merged 2026-02-28) — +340 -120
- **#141** — Remove session middleware (@bob, merged 2026-02-27) — +12 -89

### Impact Assessment

- **Risk level**: High
- **Areas affected**: Authentication, API middleware, client SDKs
- **Action items**: Update all API clients to use Bearer tokens

### Screenshots & Videos

|                                                                     |                                                                                                                      |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |

---

## No Changes

- config-service (already up to date)

报告中的所有引用都是可点击的：PR编号链接到GitHub PR，提交SHA链接到提交页面， @author 提到指向GitHub配置文件的链接，以及指向存储库的仓库名称链接。外部链接在新选项卡中打开。

个人资料特定摘要

在生成基础报告之后， /sync 为中定义的每个配置文件创建定制摘要 nosce.config.yml每个摘要都通过特定角色的视角重新分析了相同的变化：

摘要与基础报告一起存储：

~/.nosce/output/reports/
  2026-02-28.md          # Full base report
  2026-02-28/            # Profile summaries
    engineer.md
    product.md
    sales.md

再次运行它

你第二次跑步 /sync，它只接收自上次运行以来的更改。该州被追踪 ~/.nosce/output/state.json.

要强制指定特定日期： /sync ~/github/my-platform --date 2026-02-27

生成文档

这 /docs 技能

/docs [input-path] [--output path] [--full] [submodule-name]

它的作用：

1. 倒像 .gitmodules 查找子模块
2. 对于每个子模块，扫描关键文件：README、Dockerfiles、API规范（proto、OpenAPI）、数据库模式（migrations、Prisma）、入口点、依赖文件
3. Claude综合了全面的架构文档

例子：

/docs ~/github/my-platform

你得到了什么 --文件在 ~/.nosce/output/docs/:

更新文档

跑 /docs 同样，它只重新分析自上次运行以来发生变化的子模块。要强制完全再生： /docs ~/github/my-platform --full

要分析单个子模块： /docs ~/github/my-platform auth-service

包级文件

对于单仓库（包含多个包）的子模块， /docs 在子模块目录中生成每个包的文档。这些可以在每个子模块下的web UI中浏览。

手动注释

添加克劳德将在再生过程中保留的注释：

## Architecture

(Claude's auto-generated content)

> Note: The WebSocket feature is experimental. Do not expose in production.

任何介于 ` 和 ` 永远不会被覆盖。

浏览结果

您有三种方法可以访问生成的内容。

1.直接读取文件

它们只是标记文件：

cat ~/.nosce/output/reports/2026-02-28.md
ls ~/.nosce/output/docs/

2.Web用户界面

启动web服务器：

nosce --output-dir ~/.nosce/output serve

打开http://localhost:3000.你得到：

• 根据请求微调器反馈 在终端中-每个API请求都显示一个braille-dot微调器，该微调器在成功时解析为绿色复选标记，在失败时解析为红十字，并显示经过的时间
• 配置文件选择器 在侧栏顶部，在工程师、产品和销售之间切换，查看特定角色的报告摘要
• 带有所有报告、文档类别和子模块的侧栏导航
• 所有内容的全文搜索
• Markdown渲染为HTML，语法突出显示
• 屏幕截图和视频库 --带有PR截图的可折叠面板，按repo/PR分组，带有灯箱查看器
• 命令选项板 --报刊 Cmd+K （或 Ctrl+K)在不离开当前页面的情况下搜索所有内容
• 目录 --在文档和报告页面上使用带有活动标题跟踪的粘性侧边栏TOC
• 交互式美人鱼图 --平移、缩放，然后双击重置；具有亮/暗模式的主题开关
• 可点击参考 --PR编号、提交SHA、仓库名称和作者提及都是指向GitHub的标记链接
• 外部链接在新选项卡中打开 --全部 http/https 链接获取 target="_blank" 自动地
• Catppuccin颜色主题（摩卡深色/拿铁浅色，符合您的操作系统偏好）

您选择的配置文件将保存在浏览器中，并在会话中持续存在。

选项：

# Custom port
nosce --output-dir ~/.nosce/output serve --port 8080

# Bind to all interfaces (not just localhost)
nosce --output-dir ~/.nosce/output serve --host 0.0.0.0

# Run as a background daemon
nosce --output-dir ~/.nosce/output serve -d

# Stop a running daemon
nosce stop

3.MCP服务器

MCP服务器允许其他Claude会话查询您生成的文档和报告。这是最强大的选项——你可以问Claude自然语言问题，它会检索相关文档。

看 MCP服务器 下面是设置。

MCP服务器

设置

将nosce添加到您的Claude Code MCP配置中。您可以按项目或全球范围执行此操作。

每个项目 --创建 .mcp.json 在任何项目中：

{
  "mcpServers": {
    "nosce": {
      "type": "stdio",
      "command": "/absolute/path/to/nosce/target/release/nosce",
      "args": ["--output-dir", "~/.nosce/output"]
    }
  }
}

或者通过CLI：

claude mcp add --scope user --transport stdio nosce \
  /absolute/path/to/nosce/target/release/nosce \
  -- --output-dir ~/.nosce/output

如果nosce已经在你的 PATH 你已经设置好了 NOSCE_OUTPUT_DIR （例如通过 nosce init):

claude mcp add --scope user --transport stdio nosce \
  $(which nosce) \
  -- --output-dir $(NOSCE_OUTPUT_DIR)

可用工具

配置后，Claude可以在任何会话中访问这些工具：

示例提示

在MCP服务器运行的情况下，您可以在任何项目中询问Claude：

• “昨天身份验证服务发生了什么变化？”
• “显示用户服务的数据库架构”
• “我们平台的总体架构是什么？”
• “在文档中搜索与WebSocket相关的任何内容”
• “给我上周支付服务的更新日志”

网页用户界面

发展

要使用web UI，请执行以下操作：

# Terminal 1: Start the Rust web server (serves the API)
cd cli
cargo run -- --output-dir ~/.nosce/output serve

# Terminal 2: Start Vite dev server (hot reload)
cd webui
npm install
npm run dev

Vite代理 /api/* 在端口3000上向Rust服务器发送请求。打开http://localhost:5173.

生产建设

cd webui
npm run build        # Outputs to cli/static/
cd ..
cargo build --release  # Embeds the web UI into the binary

web UI嵌入到 nosce 二进制编译时使用 rust-embed。更改任何web UI后，您必须重新运行 cargo build 新资产生效。这使得二进制文件完全自包含——没有外部 static/ 运行时需要目录。

技术栈

• Preact公司 + TypeScript （严格模式）
• Tailwind CSS 随着 猫布丁 调色板
• 维特 对于构建
• ESLint（严格+风格类型检查）+Prettier

项目结构

nosce/
├── .claude/
│   └── skills/
│       ├── sync/SKILL.md         # /sync — daily changelog generation
│       └── docs/SKILL.md         # /docs — architecture documentation
├── .mcp.json                      # MCP server config (for this repo)
├── nosce.config.yml               # Default configuration
│
├── cli/                           # Rust: CLI + MCP server + web server
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs               # CLI (clap): mcp | serve | stop subcommands
│       ├── config.rs             # Profile definitions + nosce.config.yml loader
│       ├── server.rs             # MCP tools + resources (rmcp)
│       ├── web.rs                # HTTP API + embedded static files (axum, rust-embed)
│       └── fs_ops.rs             # Non-blocking filesystem operations
│
├── webui/                         # Preact SPA
│   ├── package.json
│   ├── tsconfig.json             # Strict TypeScript
│   ├── eslint.config.js          # Strict + stylistic ESLint
│   ├── .prettierrc.json
│   ├── vite.config.ts
│   ├── tailwind.config.js        # Catppuccin Latte + Mocha
│   └── src/
│       ├── main.tsx
│       ├── app.tsx               # Router + ProfileProvider
│       ├── types.ts              # API response types + ProfileInfo
│       ├── constants.ts          # Color/icon mappings for tags, repos, docs
│       ├── index.css             # Tailwind + Catppuccin CSS vars
│       ├── context/
│       │   └── ProfileContext.tsx # Profile state (localStorage-backed)
│       ├── components/
│       │   ├── Sidebar.tsx
│       │   ├── ProfileSelector.tsx  # Role selector dropdown
│       │   ├── MarkdownContent.tsx  # Markdown + Mermaid pan-zoom + code copy
│       │   ├── MediaGallery.tsx     # PR screenshots/videos gallery + lightbox
│       │   ├── CommandPalette.tsx   # Cmd+K global search palette
│       │   └── TableOfContents.tsx  # Sticky TOC with active heading tracking
│       └── pages/
│           ├── Home.tsx
│           ├── ReportsList.tsx
│           ├── ReportView.tsx    # Profile-aware report fetching
│           ├── DocView.tsx
│           ├── SubmoduleView.tsx
│           ├── PackageView.tsx   # Per-package docs for monorepo submodules
│           └── Search.tsx
│
├── README.md
└── LICENSE

输出目录结构

运行后 /sync 和 /docs，您的输出目录如下：

~/.nosce/output/
├── state.json                     # Tracks last-synced SHA per submodule
├── reports/
│   ├── 2026-02-28.md             # Base daily report (full)
│   ├── 2026-02-28/               # Profile-specific summaries
│   │   ├── engineer.md
│   │   ├── product.md
│   │   └── sales.md
│   ├── 2026-02-27.md
│   └── ...
├── media/                         # Screenshots & videos from PRs
│   └── 2026-02-28/
│       ├── manifest.json          # Metadata: filename, repo, PR, author
│       ├── auth-service-pr142-1.png
│       ├── auth-service-pr142-2.png
│       └── ...
└── docs/
    ├── overview.md               # Platform overview
    ├── architecture.md           # Mermaid diagrams, service topology
    ├── apis.md                   # All API contracts
    ├── databases.md              # All database schemas
    ├── dependencies.md           # Service dependency graph
    └── submodules/
        ├── auth-service.md       # Per-submodule deep dive
        ├── user-service.md
        └── ...

从源头构建

Web UI（先构建）

cd webui
npm install
npm run build       # Production build -> cli/static/
npm run dev         # Dev server with hot reload
npm run typecheck   # TypeScript check
npm run lint        # ESLint
npm run format      # Prettier check

Rust服务器

编译Rust二进制文件之前必须构建web UI-- rust-embed 将所有内容嵌入 cli/static/ 在编译时将其转换为二进制文件。

cargo build --release

二元的： target/release/nosce （自包含，包括web UI资产）

故障排除

“输出目录不存在”

创建它：

mkdir -p ~/.nosce/output

/sync 表示“未提供输入路径”

要么：

• 将其作为论据传递： /sync /path/to/your/repo
• 或者设置它 nosce.config.yml:

  input: /path/to/your/repo

报告中没有PR数据

这 /sync 技能使用 gh CLI用于获取合并的PR。如果缺少PR：

1. 安装 gh: brew install gh
2. 身份验证： gh auth login
3. 集 github_owner 在 nosce.config.yml

这项技能不用 gh --你只是不会在报告中看到公关信息。

Web UI显示“前端未构建”

web UI在编译时嵌入到二进制文件中。构建它，然后重新编译：

cd webui
npm install
npm run build
cd ..
cargo build --release

然后重新启动服务器。

Web UI显示“尚无文档”

首先运行技能以生成内容：

/sync /path/to/your/repo
/docs /path/to/your/repo

MCP服务器未连接

检查：

1. 二进制路径 .mcp.json 绝对正确
2. 输出目录存在并且包含内容
3. 您可以手动运行它： nosce --output-dir ~/.nosce/output --help

“你的平台回购”——这是什么意思？

Nosse希望有一个git仓库 .gitmodules --这意味着它包含其他git repos作为子模块。如果你有一个没有子模块的monorepo，nosce不是合适的工具。

要检查repo是否有子模块：

cat /path/to/your/repo/.gitmodules

如果该文件存在并列出了子模块，那么就可以了。

许可证

麻省理工学院 - Julien Andreu