PyNoti

Semantic notes, foldable cells, and Markdown explanations for Python, TypeScript, and C/C++ source files.

中文说明在本文底部，内容与英文版保持一致。

PyNoti is a VS Code extension that opens standard Python, TypeScript, and C/C++ files as a structured reading and annotation surface. It does not turn your code into a notebook, does not require a separate frontend, and does not introduce a new source format like .ipynb. Your source files stay source files; PyNoti changes the visual structure around them so existing projects become easier to scan, explain, and hand off.

The GIFs below are captured from the actual PyNoti webview UI.

Overview

Open a supported source file with PyNoti and it becomes a tree of language-aware cells: imports/includes, classes/structs, namespaces, interfaces/types, enums, functions, methods, Markdown notes, source panels, and summaries.

This gives a plain source repository a notebook-like reading surface while keeping the codebase unchanged. Python, TypeScript, and C/C++ use language-specific structural parsers and cell templates; the shared review layers remain consistent across languages.

Built for Maintainable Vibe Coding

Vibe coding is fast, but a growing project can branch into too many implementation paths for both people and agents to review. PyNoti adds lightweight boundaries that make that complexity easier to follow:

• File overview: a collapsible Markdown description at the top of each file explains its responsibility before you read the cells.
• AI Annotation: a concise review aid for a cell's purpose and role. It is empty and inactive by default; an agent may generate it only after you explicitly request it and name the exact supported source files. PyNoti never scans every file automatically.
• Interface contract: an attachable Markdown specification for inputs, outputs, parameters, errors, and boundaries. It lets an agent change internal implementation while keeping the externally observable behavior clear.
• Unified $pynoti skill: modular references teach Claude Code, Codex, Cursor, and other agents how to read PyNoti without loading every document or spending tokens in the background.

All of these layers are stored in the project-level PyNoti/ metadata folder. Source code, comments, and docstrings remain untouched unless you explicitly edit source through a supported cell action. AI-related actions are opt-in and file-scoped to keep developer control, review quality, and API costs predictable.

Fold Fast, Read Faster

Large Python files are often hard to read because every implementation detail competes for attention. PyNoti cells can be collapsed at the file level, expanded one layer at a time, or expanded recursively.

The practical benefit is focus: quickly locate the relevant class, function, parameter group, or method; hide cells that do not matter for the current task; and keep only the useful summary visible while reading.

Notes, Long Explanations, Formulas, and Images

PyNoti gives each cell a place for annotations and long-form explanations. Use it for formulas, implementation notes, background theory, screenshots, diagrams, and reasoning that should stay next to the code.

The long explanation paste area supports Markdown preview, code snippets, simple formula rendering, images, and a larger reading window. This is useful when a function needs context that would be too noisy inside the source file itself.

Semantic Cells Inside Functions and Classes

PyNoti cells are not limited to Python syntax boundaries. A class or function can contain smaller semantic cells whose boundaries follow purpose, workflow, or meaning. Each cell can also have a short summary, so readers can quickly scan and skip blocks that are irrelevant to the current task.

For example, one method can be split into "validate inputs" and "build logits" cells even though both sections live inside the same function. The same review surface can show a C++ class with inherited behavior or a TypeScript interface and generic function. Read the structure first, then open the exact source block when the implementation matters.

Clean Python Files, Portable PyNoti Metadata

PyNoti keeps your .py files clean. Notes, aliases, Markdown-only cells, and attachments are stored in a project-level PyNoti/ folder that mirrors the Python project path one-to-one.

Example:

src/pipeline/models/tiny_classifier.py
PyNoti/src/pipeline/models/tiny_classifier.py.pynoti.json
PyNoti/attachments/images/...

When the repository is cloned or pulled with Git, the recorded notes travel with the root PyNoti/ folder and are restored when the Python file is opened again. The mirrored paths also make metadata easy to find if you ever need to inspect or copy it manually.

For simple one-file transfer, send the Python file together with its sidecar metadata file:

model.py
model.py.pynoti.json

PyNoti will load the sidecar file too. The same project-level mapping is used for TypeScript and C/C++ files. If both the project-level metadata and the sidecar file exist, the project-level PyNoti/ metadata takes priority.

What You Can Do

• Open .py, .ts, .tsx, .c, .cc, .cpp, .cxx, .h, .hh, .hpp, and .hxx files in a structured custom editor.
• Browse language-specific classes, structs, namespaces, interfaces/types, enums, functions, methods, imports/includes, semantic code blocks, and Markdown note cells.
• Collapse and expand cells globally or locally.
• Rename class/function/method definitions from the title bar while syncing source code.
• Add aliases for import and parameter cells without changing Python source.
• Edit summaries, notes, input/output descriptions, data-flow notes, parameter notes, and long explanations.
• Insert Markdown-only cells and images without adding anything to the .py file.
• Move, delete, and create cells from the PyNoti interface.
• Run the current Python file and inspect output inside the PyNoti panel. TypeScript and C/C++ intentionally do not show a run button; PyNoti focuses on their structural review surface.

Quick Start

1. Install PyNoti from the VS Code Marketplace or from a .vsix package.
2. Open a supported source file.
3. Run PyNoti: Open Structured Python Editor from the Command Palette, or use Open With... and choose PyNoti Structured Source.
4. Click a cell title, summary, note area, source tab, or cell operation menu to organize the file.

For agent-assisted workflows, explicitly ask the agent to use PyNoti and list the exact supported source files. Use the file overview for a whole-file purpose, an interface contract for developer-defined behavior, and AI Annotation only when you want a concise agent-generated review description.

Settings

• pynoti.renderSourceComments: controls source comment rendering. Values: hidden, collapsed, visible. Default: collapsed.
• pynoti.pythonPath: Python executable used by PyNoti: Run Current Python File. Default: python3.

Current Status

PyNoti 0.0.4 is an early multilingual preview. Python remains fully supported, while TypeScript and C/C++ focus on structural review, annotations, interface contracts, and language-aware source editing. Extremely advanced syntax and unusual layouts may still reveal parser edge cases.

PyNoti 中文说明

面向 Python、TypeScript 和 C/C++ 源文件的语义附注、可折叠 cell 与 Markdown 解释层。

PyNoti 是一个 VS Code 插件，可以把标准 Python、TypeScript 和 C/C++ 文件打开为结构化阅读和批注界面。它不会把代码变成 notebook，不需要额外前端，也不会引入 .ipynb 这类新的源码格式。你的源文件仍然是源文件；PyNoti 只是改变它的视觉结构，让现有工程更容易阅读、解释和交接。

下面的动态图均来自真实的 PyNoti webview 界面。

总览

用 PyNoti 打开受支持的源文件后，文件会变成一棵语言感知的 cell 树：imports/includes、class/struct、namespace、interface/type、enum、function、method、Markdown note、源码面板和摘要都会被组织起来。

这让普通源代码仓库获得类似 notebook 的阅读体验，但代码库本身保持不变。Python、TypeScript 和 C/C++ 使用各自的结构解析和 cell 模板，而文件说明、附注、接口规范等 review 层保持一致。

为可维护的 Vibe Coding 设计

Vibe coding 的速度很快，但工程变大后，实现路线会不断分岔，人和 agent 都很难快速 review。PyNoti 增加了几层轻量边界，让复杂度更容易被理解和控制：

• 文件级功能说明：在文件顶部提供可折叠的 Markdown 说明，打开文件时先了解整个文件负责什么。
• AI 附注：简洁说明某个 cell 的功能和作用。它默认为空、默认关闭；只有你明确要求并列出具体受支持源文件后，agent 才可以生成，PyNoti 不会自动遍历所有文件。
• 接口规范：附着在现有 cell 上的 Markdown 规范，用来约束输入、输出、参数、错误和边界。agent 可以自由调整内部实现，但外部可观察行为必须保持清晰。
• 统一 $pynoti skill：通过模块化资料帮助 Claude Code、Codex、Cursor 等 agent 学会读取和操作 PyNoti，不默认加载全部文档，也不会在后台消耗 token。

这些内容全部保存在项目级 PyNoti/ metadata 文件夹中。源代码、注释和 docstring 保持不变，除非开发者明确通过支持的 cell 操作编辑源码。所有 AI 相关操作都必须由开发者明确启用，并且限定到具体文件，以保持选择权、review 质量和 API 成本可控。

快速折叠，快速阅读

大型 Python 文件难读，常常是因为每一段实现细节都在争夺注意力。PyNoti 的 cell 可以全局折叠、只展开一级，也可以递归全部展开。

它的实际价值是提升注意力：快速定位相关 class、function、参数组或 method；隐藏当前任务不需要的 cell；阅读时只保留有用的摘要和结构。

附注、长解释、公式和图片

PyNoti 给每个 cell 提供附注和长解释区域。你可以把公式、实现思路、背景原理、截图、图示和推理过程写在代码旁边。

长解释粘贴区支持 Markdown 预览、代码片段、简单公式渲染、图片和更大的阅读窗口。当一个函数需要很多背景信息，而这些信息又不适合塞进源码时，这个区域会非常有用。

class 和 function 内部也能按语义分 cell

PyNoti 的 cell 不局限于 Python 语法边界。一个 class 或 function 内部也可以继续拆成更小的语义 cell，边界可以按功能、流程或语义来划分。每个 cell 还可以写一个短摘要，方便读者快速扫读并跳过当前任务不重要的模块。

例如，同一个 method 可以拆成 validate inputs 和 build logits 两个 cell，即使它们仍然位于同一个 function 内。C++ 的继承类、虚函数和 operator，TypeScript 的 interface、泛型 type 和函数也可以先以结构方式 review，再打开源码面板查看实现。

干净的 Python 文件，可传播的 PyNoti 元数据

PyNoti 保持 .py 文件干净。备注、别名、纯 Markdown cell 和附件会存储在项目级 PyNoti/ 文件夹中，并且这个文件夹会一比一镜像 Python 工程路径。

示例：

src/pipeline/models/tiny_classifier.py
PyNoti/src/pipeline/models/tiny_classifier.py.pynoti.json
PyNoti/attachments/images/...

当仓库通过 Git 克隆或拉取时，记录的笔记会跟随根目录下的 PyNoti/ 文件夹一起传播。再次打开 Python 文件时，备注和结构会自动恢复。路径镜像也方便用户在需要时手动查找或复制对应元数据。

如果只是简单发送单个 Python 文件，也可以把 Python 文件和旁路元数据文件一起发送：

model.py
model.py.pynoti.json

PyNoti 也会读取这个旁路文件。TypeScript 和 C/C++ 使用同样的项目级映射规则。如果项目级元数据和旁路文件同时存在，则优先使用项目级 PyNoti/ 元数据。

你可以做什么

• 用结构化自定义编辑器打开 .py、.ts、.tsx、.c、.cc、.cpp、.cxx、.h、.hh、.hpp 和 .hxx 文件。
• 浏览语言对应的 class、struct、namespace、interface/type、enum、function、method、import/include、语义代码块和 Markdown note cell。
• 全局或局部折叠/展开 cell。
• 在标题栏修改 class/function/method 名称，并同步回源码。
• 给 import 和 parameter cell 添加别名，而不修改 Python 源码。
• 编辑摘要、附注、输入/返回说明、数据流说明、参数说明和长解释。
• 插入纯 Markdown cell 和图片，而不向 .py 文件写入任何内容。
• 在 PyNoti 界面里移动、删除和创建 cell。
• 运行当前 Python 文件，并在 PyNoti 面板中查看输出。TypeScript 和 C/C++ 不显示运行按钮，PyNoti 对它们专注于结构化 review。

快速开始

1. 从 VS Code Marketplace 或 .vsix 包安装 PyNoti。
2. 打开一个受支持的源文件。
3. 在命令面板运行 PyNoti: Open Structured Python Editor，或者使用 Open With... 并选择 PyNoti Structured Source。
4. 点击 cell 标题、摘要、附注区域、源码 tab 或 cell 操作菜单来整理文件。

如果要使用 agent 辅助开发，请明确要求 agent 使用 PyNoti，并列出具体的受支持源文件。文件级说明用于描述整个文件的职责，接口规范用于定义开发者要求的输入输出行为，AI 附注只在你需要简洁的 agent review 说明时启用。

设置

• pynoti.renderSourceComments：控制源码注释显示方式。可选值：hidden、collapsed、visible。默认值：collapsed。
• pynoti.pythonPath：PyNoti: Run Current Python File 使用的 Python 可执行文件。默认值：python3。

当前状态

PyNoti 0.0.4 是早期多语言预览版本。Python 仍然完整支持，TypeScript 和 C/C++ 主要支持结构化 review、附注、接口规范和语言感知的源码编辑。极复杂语法和特殊布局仍可能暴露解析边界，欢迎反馈真实项目中的问题。