asta-documents

Asta 文档管理

此技能通过 asta documents CLI 提供完整的文档管理功能，用于跟踪研究论文、文档和资源。

功能： 在本地索引中跟踪文档元数据（URL、摘要、标签）。可以将它视为具备强大搜索功能的智能书签管理器。

默认索引位置： .asta/documents/index.yaml（相对于当前工作目录）。使用默认位置时，--index-path 标志为可选项；仅在使用自定义索引位置或远程索引时才需要它。

自动索引 .asta 文档

重要： 当其他 Asta 技能（如文献研究）将文档写入 .asta/（当前工作目录中）时，应自动将其编入文档库。这能确保跟踪并搜索所有由 Asta 生成的文档。

工作流：

1. 在任何 Asta 技能将文件写入 .asta/ 后（例如文献报告、论文集）
2. 扫描目录以查找新文档
3. 对于每份文档，使用适当的元数据将其添加到索引中：
   • name：从文件名或文档标题中提取
   • url：使用指向本地路径的 file:// URL（file:// URL 请使用绝对路径）
   • summary：从文档内容中提取，或使用简短描述
   • tags：添加相关标签（例如“asta-generated”、“literature-report”等）
   • mime-type：根据文件扩展名检测（例如“text/markdown”、“application/pdf”）

示例：

# After a literature report is written to .asta/literature/report/2024-01-15-ml.md
# Convert relative path to absolute for file:// URL
REPORT_PATH="$(pwd)/.asta/literature/report/2024-01-15-ml.md"
asta documents add "file://${REPORT_PATH}" \
  --name="Literature Report: Machine Learning" \
  --summary="Comprehensive report on machine learning papers from 2023-2024" \
  --tags="asta-generated,literature-report,ml" \
  --mime-type="text/markdown"

快速命令参考

为任何命令添加 --json 标志，以获取机器可读的输出。 默认使用 .asta/documents/index.yaml（自定义位置请添加 --index-path <file>）。

# List documents
asta documents list
asta documents list --tags="ai,research"

# Search documents (by field)
asta documents search --summary="query"
asta documents search --name="title words"
asta documents search --tags="ai,nlp"
asta documents search --extra=".year > 2020"

# Multi-field search (intersection - matches ALL)
asta documents search --summary="transformers" --tags="ai"

# Multi-field search (union - matches ANY)
asta documents search --summary="transformers" --name="BERT" --union

# Add document (use absolute path for file:// URLs)
asta documents add <url> \
  --name="Title" \
  --summary="Description" \
  --tags="tag1,tag2" \
  --extra='{"author": "Smith et al", "year": 2024, "venue": "NeurIPS"}'

# Get document metadata
asta documents get <uuid>

# Update document
asta documents update <uuid> \
  --name="New Title" \
  --tags="new,tags"

# Fetch document content
asta documents fetch <uuid> -o /tmp/document.pdf

# Manage tags
asta documents add-tags <uuid> --tags="new,tags"
asta documents remove-tags <uuid> --tags="old,tags"

# Cache management
asta documents cache list
asta documents cache stats
asta documents cache clean --days 7

# Summary information (document counts)
asta documents show

所有操作始终使用命令行界面，以确保正确管理索引和缓存。 避免直接对索引文件执行读取或写入操作。

使用远程索引（asta:// URL）

Asta 文档可以使用 asta:// URL 方案引用远程索引。这样便可共享托管在网络上的文档集合。

URL 格式：

asta://{url-encoded-index-url}/{uuid}

其中：

• {url-encoded-index-url} 是远程 index.yaml 文件 URL 经过 URL 编码后的值
• {uuid} 是 10 个字符的文档标识符

示例：

# Actual index URL: https://example.com/research/index.yaml
# Asta URL: asta://https%3A%2F%2Fexample.com%2Fresearch%2Findex.yaml/6MNxGbWGRC

工作流：

遇到 asta:// URL 时，请按以下步骤操作：

1. 解析 URL，提取经过编码的索引 URL 和文档 UUID
2. 对索引 URL 进行 URL 解码
3. 将远程索引下载到本地临时文件
4. 使用 --index-path 参数访问文档

示例：

# Given an asta:// URL
ASTA_URL="asta://https%3A%2F%2Fexample.com%2Fresearch%2Findex.yaml/6MNxGbWGRC"

# 1. Parse the URL components (extract encoded index URL and UUID)
ENCODED_INDEX_URL=$(echo "$ASTA_URL" | sed 's|^asta://||' | sed 's|/[^/]*$||')
UUID=$(echo "$ASTA_URL" | sed 's|.*/||')

# 2. URL-decode the index URL
INDEX_URL=$(python3 -c "import urllib.parse; print(urllib.parse.unquote('$ENCODED_INDEX_URL'))")

# 3. Download the remote index
curl -s -o /tmp/remote-index.yaml "$INDEX_URL"

# 4. Get document metadata using --index-path
asta documents get "$UUID" --index-path /tmp/remote-index.yaml

# 5. Fetch document content
asta documents fetch "$UUID" --index-path /tmp/remote-index.yaml -o /tmp/document.pdf

使用远程索引的常见操作：

# After downloading and decoding the index URL (see examples above)
# Assume TEMP_INDEX points to the downloaded index file

# Search remote index
asta documents search --summary="query" --index-path "$TEMP_INDEX"

# List all documents in remote index
asta documents list --index-path "$TEMP_INDEX"

# Get metadata for specific document
asta documents get "$UUID" --index-path "$TEMP_INDEX"

# Search and fetch from remote index
asta documents search --summary="transformers" --index-path "$TEMP_INDEX" --show-scores
asta documents fetch "$UUID" --index-path "$TEMP_INDEX" -o result.pdf

重要说明：

• --index-path 参数适用于所有读取命令（list、search、get、fetch）
• 以这种方式访问的远程索引为只读（不支持 add/update/remove 操作）
• 可以在本地缓存下载的索引，以避免重复下载
• 索引 URL 部分经过 URL 编码，使用前必须先解码
• 解码后的 URL 支持：http://、https://、file://、s3://、gs://
• 使用前始终验证索引文件存在且为有效的 YAML

完整工作流示例：

# User provides: asta://https%3A%2F%2Fai.example.org%2Fpapers%2Findex.yaml/AbC123XyZ9

# Step 1: Extract components
ASTA_URL="asta://https%3A%2F%2Fai.example.org%2Fpapers%2Findex.yaml/AbC123XyZ9"
ENCODED_INDEX_URL=$(echo "$ASTA_URL" | sed 's|^asta://||' | sed 's|/[^/]*$||')
UUID=$(echo "$ASTA_URL" | sed 's|.*/||')

# Step 2: URL-decode the index URL
INDEX_URL=$(python3 -c "import urllib.parse; print(urllib.parse.unquote('$ENCODED_INDEX_URL'))")
# Result: https://ai.example.org/papers/index.yaml

# Step 3: Download index to temp location
TEMP_INDEX="/tmp/asta-index-$(date +%s).yaml"
curl -s -o "$TEMP_INDEX" "$INDEX_URL"

# Step 4: Verify download succeeded
if [ ! -f "$TEMP_INDEX" ]; then
    echo "Failed to download index from $INDEX_URL"
    exit 1
fi

# Step 5: Access the document
asta documents get "$UUID" --index-path "$TEMP_INDEX"
asta documents fetch "$UUID" --index-path "$TEMP_INDEX" -o /tmp/paper.pdf

# Step 6: Read the content
# Read(/tmp/paper.pdf)

获取文档内容

索引仅存储元数据。可以通过文档 URL 获取其内容。fetch 命令会获取内容并在本地缓存，以供日后使用。

获取到文件（并自动缓存）：

asta documents fetch <uuid> -o /tmp/document.pdf

支持的 URL 协议

系统支持多种文档 URL 协议：

本地和网络：

• http:// 和 https:// - 网络 URL（使用 curl）
• file:// - 本地文件系统（使用 curl）

云存储：

• s3:// - Amazon S3（需要 AWS CLI）
• gs:// - Google Cloud Storage（需要 gsutil）

云存储设置：

对于 S3：

# Install AWS CLI
brew install awscli  # macOS
pip install awscli   # or via pip

# Configure credentials
aws configure
# Or use: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_PROFILE

对于 GCS：

# Install Google Cloud SDK
brew install --cask google-cloud-sdk  # macOS

# Authenticate
gcloud auth login
# Or use: GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

示例：

# Add document from S3
asta documents add s3://my-bucket/papers/research.pdf \
  --name="Research Paper" \
  --summary="ML research findings" \
  --tags="ml,research"

# Add document from GCS
asta documents add gs://my-bucket/docs/spec.pdf \
  --name="Technical Spec" \
  --summary="System specifications" \
  --tags="docs"

# Fetch works the same for all protocols
asta documents fetch <uuid> -o local-copy.pdf

缓存管理

列出缓存项：

asta documents cache list

显示缓存统计信息：

asta documents cache stats

清理旧缓存条目：

# Remove items older than N days
asta documents cache clean --days 14

清空整个缓存：

asta documents cache clear
asta documents cache clear -y  # Skip confirmation

显示特定项的详细信息：

asta documents cache info <hash>

常见工作流

工作流 1：索引 Asta 生成的文档

# After literature find writes to .asta/
# List all files in .asta/
ls -la .asta/

# For each new document, add to index (convert to absolute path for file:// URL)
REPORT_PATH="$(pwd)/.asta/literature/report/literature-report.md"
asta documents add "file://${REPORT_PATH}" \
  --name="Literature Report: Transformers" \
  --summary="Research findings on transformer architectures" \
  --tags="asta-generated,literature-report,transformers" \
  --mime-type="text/markdown"

# Now the document is searchable
asta documents search --tags="asta-generated"

工作流 2：添加和整理论文

# Add research paper
asta documents add https://arxiv.org/pdf/1706.03762.pdf \
  --name="Attention Is All You Need" \
  --summary="Seminal paper introducing Transformer architecture" \
  --tags="ai,research,nlp,transformers" \
  --mime-type="application/pdf" \
  --extra='{"author": "Vaswani et al", "year": 2017, "venue": "NeurIPS"}'

# Search papers by tag
asta documents search --tags="transformers"

工作流 3：搜索和获取

# Search for relevant documents
asta documents search --summary="transformer architecture" --show-scores

# Get metadata for top result (using UUID from search results)
asta documents get 6MNxGbWGRC

# Fetch content
asta documents fetch 6MNxGbWGRC -o /tmp/paper.pdf -q

# Read with PDF support
# Read(/tmp/paper.pdf)

工作流 4：使用 JSON 处理进行搜索

# Search and extract UUIDs
RESULTS=$(asta documents search --summary="query" --json)

# Get first UUID (example with Python)
UUID=$(echo "$RESULTS" | python3 -c "import sys,json; results=json.load(sys.stdin); print(results[0]['result']['uuid'] if results else '')")

# Fetch that document
asta documents fetch "$UUID" -o result.pdf

工作流 5：批量管理标签

# List documents with old tag
DOCS=$(asta documents list --tags="old-tag" --json)

# For each, remove old tag and add new
for uuid in $(echo "$DOCS" | python3 -c "import sys,json; print('\\n'.join([d['uuid'] for d in json.load(sys.stdin)]))"); do
    asta documents remove-tags "$uuid" --tags="old-tag"
    asta documents add-tags "$uuid" --tags="new-tag"
done

工作流 6：更新多个字段

# Get current metadata (using UUID)
asta documents get 6MNxGbWGRC

# Update multiple fields
asta documents update 6MNxGbWGRC \
  --name="Updated Title" \
  --summary="Updated summary with more details" \
  --tags="updated,revised,2025"

工作流 7：缓存维护

# Check cache usage
asta documents cache stats

# List what's cached
asta documents cache list

# Remove old entries if cache is large
asta documents cache clean --days 7

# Verify cache reduction
asta documents cache stats

按字段搜索

Asta 会针对不同文档字段采用优化的搜索策略。你可以搜索单个字段，也可以通过交集／并集模式组合多个字段。

单字段搜索

--summary（摘要搜索）：

• 自动使用最佳可用方法：
  • 混合搜索（BM25 + 语义嵌入）→ 质量最佳
  • BM25（关键词相关性排序）→ 基于索引，速度快
  • FTS5（全文搜索）→ 后备方案
  • 简单搜索（子串匹配）→ 始终可用
• 针对自然语言查询进行了优化
• 能理解语义
• 生成相关性分数以进行排序
• 示例：asta documents search --summary="papers about transformers"

--name（名称搜索）：

• 简单的不区分大小写的词语匹配
• 将查询拆分为多个词，并匹配名称中的任意词
• 分数 =（匹配词数 / 查询词总数）
• 速度快，无需建立索引
• 生成匹配分数以进行排序
• 示例：asta documents search --name="Attention"

--tags（标签搜索）：

• 使用逗号分隔的标签进行匹配
• 不区分大小写
• 作为筛选条件使用（不生成有意义的相关性分数）
• 查找包含任意匹配标签的文档
• 示例：asta documents search --tags="ai,nlp"

--extra（额外元数据搜索）：

• 类似 JSONPath 的查询语法
• 支持的运算符：>、>=、<、<=、==、contains
• 支持数值和字符串比较
• 作为筛选条件使用（不生成有意义的相关性分数）
• 示例：
  • asta documents search --extra=".year > 2020"
  • asta documents search --extra=".author contains Smith"
  • asta documents search --extra=".venue == NeurIPS"

多字段搜索

组合多个字段查询，创建强大的筛选搜索：

交集模式（默认）：

• 返回符合所有指定字段查询的文档
• 示例：asta documents search --summary="transformers" --tags="ai"
• 仅返回摘要包含 "transformers" 且标签包含 "ai" 的文档

并集模式（--union 标志）：

• 返回符合任意指定字段查询的文档
• 示例：asta documents search --summary="transformers" --name="BERT" --union
• 返回摘要包含 "transformers" 或名称包含 "BERT" 的文档

分层评分：

结果按优先级层次排序，其中标签／额外元数据用作筛选条件：

1. 摘要分数（最高优先级）——如果存在 --summary

   • 使用语义／混合搜索相关性
   • 最适合自然语言查询

2. 名称分数（中等优先级）——如果存在 --name

   • 使用词语匹配分数
   • 没有摘要查询时使用

3. 创建时间戳（最低优先级）——如果仅指定 --tags 或 --extra

   • 按创建时间排序（最新的在前）
   • 仅在没有摘要／名称查询时使用

示例：

# Summary + tags: Sorted by summary relevance (tags filter)
asta documents search --summary="machine learning" --tags="ai"

# Name + tags: Sorted by name word-match (tags filter)
asta documents search --name="Python" --tags="programming"

# Tags only: Sorted by creation timestamp
asta documents search --tags="research"

# Three fields: Summary ranks, name and extra filter
asta documents search --summary="transformers" --name="Attention" --extra=".year > 2015"

输出格式

人类可读（默认）：

• 格式化的表格和列表
• 使用颜色编码（如果终端支持）
• 显示进度消息

JSON（--json 标志）：

• 机器可读
• 包含所有字段
• 用于脚本和集成

详细模式（列表命令的 -v 标志）：

• 显示所有元数据字段
• 包含额外元数据
• 显示完整 URI 和时间戳

最佳实践

1. 自动为 Asta 文档建立索引：始终为其他技能写入 .asta/ 的文档建立索引（默认使用 .asta/documents/index.yaml）
2. 使用描述性摘要：摘要会被编入索引以供搜索
3. 保持标签一致：建立一套标签方案（例如，为自动编入索引的文档使用 "asta-generated"）
4. 使用额外的元数据：为论文保存作者、年份和发表场所
5. 让 fetch 处理缓存：不要手动检查缓存
6. 使用 JSON 编写脚本：比解析文本更可靠
7. 在脚本中使用安静模式：-q 会抑制进度消息
8. 对 file:// URL 使用绝对路径：使用 $(pwd)/ 转换相对路径，确保正确解析

故障排除

“asta-documents: command not found”

• 该命令应在首次使用时自动安装
• 验证安装：uv tool list | grep asta
• 添加到 PATH：export PATH="$HOME/.local/bin:$PATH"
• 手动安装：uv tool install git+https://github.com/allenai/asta-resource-repo.git

“Document not found”

• 验证 UUID：asta documents list --json | grep <partial-uuid>
• 检查命名空间：UUID 特定于各自的命名空间
• 确保 .asta/documents/index.yaml 中存在索引文件

“Fetch failed”

• 检查 URL 是否可访问：curl -I <url>
• 尝试强制刷新：--force
• 检查网络连接

“Search returns no results”

• 尝试使用更简单的查询词
• 使用名称或标签进行精确匹配：
  • asta documents search --name="keyword"
  • asta documents search --tags="tag"
• 检查文档是否存在：asta documents list
• 使用多个字段时，尝试并集模式：--union

“Cache is large”

• 检查大小：asta documents cache stats
• 清理旧条目：asta documents cache clean --days 7
• 如有需要，清空缓存：asta documents cache clear -y

更新

更新 asta-documents CLI：

uv tool install --reinstall git+https://github.com/allenai/asta-resource-repo.git

链接

• 仓库：https://github.com/allenai/asta-resource-repo
• 文档：https://github.com/allenai/asta-resource-repo/blob/main/README.md
• 问题反馈：https://github.com/allenai/asta-resource-repo/issues